/ Hex Artifact Content
Login

Artifact e149baf6c77cba40fa462d76e3c0b37535be6a36:


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 35 20 32 30 30 38 2f 30  n,v 1.385 2008/0
05f0: 38 2f 30 34 20 31 33 3a 34 34 3a 35 37 20 64 72  8/04 13:44:57 dr
0600: 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e 64  h Exp $.*/.#ifnd
0610: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ef _SQLITE3_H_.#
0620: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f  define _SQLITE3_
0630: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64  H_.#include <std
0640: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65  arg.h>     /* Ne
0650: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66  eded for the def
0660: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69  inition of va_li
0670: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  st */../*.** Mak
0680: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61  e sure we can ca
0690: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72  ll this stuff fr
06a0: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65  om C++..*/.#ifde
06b0: 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78  f __cplusplus.ex
06c0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69  tern "C" {.#endi
06d0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68  f.../*.** Add th
06e0: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65  e ability to ove
06f0: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a  rride 'extern'.*
0700: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
0710: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65  _EXTERN.# define
0720: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65   SQLITE_EXTERN e
0730: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  xtern.#endif../*
0740: 0a 2a 2a 20 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 43 68 6f 69 63 65 73 20 66 6f 72 20 74 68 69   Choices for thi
ac00: 73 20 76 61 6c 75 65 20 61 72 65 20 5b 53 51 4c  s value are [SQL
ac10: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
ac20: 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65  SIDE]..** New ve
ac30: 72 62 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74  rbs are likely t
ac40: 6f 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  o be added in fu
ac50: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
ac60: 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
ac70: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
ac80: 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  g(sqlite3*, int 
ac90: 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  op, ...);../*.**
aca0: 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
acb0: 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
acc0: 74 69 6e 65 73 20 7b 48 31 30 31 35 35 7d 20 3c  tines {H10155} <
acd0: 53 32 30 31 32 30 3e 0a 2a 2a 20 45 58 50 45 52  S20120>.** EXPER
ace0: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e  IMENTAL.**.** An
acf0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
ad00: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
ad10: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
ad20: 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  etween SQLite.**
ad30: 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d   and low-level m
ad40: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
ad50: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
ad60: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
ad70: 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65  used in only one
ad80: 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51   place in the SQ
ad90: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
ada0: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
adb0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
adc0: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68  his object is th
add0: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
ade0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
adf0: 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e  ()] when the con
ae00: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
ae10: 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  n is.** [SQLITE_
ae20: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
ae30: 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
ae40: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
ae50: 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
ae60: 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
ae70: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
ae80: 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
ae90: 74 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 70 70 6c  tion, an.** appl
aea0: 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63  ication can spec
aeb0: 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
aec0: 76 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ve memory alloca
aed0: 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 0a 2a  tion subsystem.*
aee0: 2a 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20  * for SQLite to 
aef0: 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
af00: 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
af10: 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
af20: 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
af30: 63 6f 6d 65 73 20 77 69 74 68 20 61 20 62 75 69  comes with a bui
af40: 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
af50: 6f 63 61 74 6f 72 20 74 68 61 74 20 69 73 0a 2a  ocator that is.*
af60: 2a 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  * perfectly adeq
af70: 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
af80: 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
af90: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
afa0: 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
afb0: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
afc0: 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
afd0: 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
afe0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
aff0: 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
b000: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
b010: 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
b020: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
b030: 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
b040: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
b050: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
b060: 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
b070: 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
b080: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
b090: 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
b0a0: 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
b0b0: 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
b0c0: 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
b0d0: 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
b0e0: 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
b0f0: 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
b100: 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
b110: 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
b120: 46 72 65 65 2c 20 61 6e 64 20 78 52 65 61 6c 6c  Free, and xReall
b130: 6f 63 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  oc methods must 
b140: 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
b150: 20 6d 61 6c 6c 6f 63 28 29 2c 20 66 72 65 65 28   malloc(), free(
b160: 29 2c 20 61 6e 64 20 72 65 61 6c 6c 6f 63 28 29  ), and realloc()
b170: 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20   functions from 
b180: 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62  the standard lib
b190: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a  rary..**.** xSiz
b1a0: 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  e should return 
b1b0: 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
b1c0: 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61  ze of a memory a
b1d0: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65  llocation.** pre
b1e0: 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
b1f0: 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72   from xMalloc or
b200: 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20   xRealloc.  The 
b210: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a  allocated size.*
b220: 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c  * is always at l
b230: 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74  east as big as t
b240: 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  he requested siz
b250: 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  e but may be lar
b260: 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ger..**.** The x
b270: 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72  Roundup method r
b280: 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c  eturns what woul
b290: 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74  d be the allocat
b2a0: 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20  ed size of.** a 
b2b0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b2c0: 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63  n given a partic
b2d0: 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73  ular requested s
b2e0: 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72  ize.  Most memor
b2f0: 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20  y.** allocators 
b300: 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20  round up memory 
b310: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c  allocations at l
b320: 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74  east to the next
b330: 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20   multiple.** of 
b340: 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74  8.  Some allocat
b350: 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20  ors round up to 
b360: 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c  a larger multipl
b370: 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20  e or to a power 
b380: 6f 66 20 32 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  of 2..**.** The 
b390: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
b3a0: 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
b3b0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
b3c0: 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (For example,.**
b3d0: 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
b3e0: 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
b3f0: 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
b400: 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
b410: 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
b420: 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
b430: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
b440: 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
b450: 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
b460: 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
b470: 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
b480: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
b490: 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
b4a0: 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
b4b0: 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
b4c0: 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
b4d0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
b4e0: 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
b4f0: 77 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  wn..*/.typedef s
b500: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
b510: 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  m_methods sqlite
b520: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73  3_mem_methods;.s
b530: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
b540: 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f  m_methods {.  vo
b550: 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69  id *(*xMalloc)(i
b560: 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20  nt);         /* 
b570: 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
b580: 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  n function */.  
b590: 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f  void (*xFree)(vo
b5a0: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f  id*);          /
b5b0: 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61  * Free a prior a
b5c0: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76  llocation */.  v
b5d0: 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29  oid *(*xRealloc)
b5e0: 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a  (void*,int);  /*
b5f0: 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63   Resize an alloc
b600: 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
b610: 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20  *xSize)(void*); 
b620: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74            /* Ret
b630: 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  urn the size of 
b640: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
b650: 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75  .  int (*xRoundu
b660: 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  p)(int);        
b670: 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65    /* Round up re
b680: 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c  quest size to al
b690: 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f  location size */
b6a0: 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28  .  int (*xInit)(
b6b0: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
b6c0: 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20    /* Initialize 
b6d0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
b6e0: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28  ator */.  void (
b6f0: 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64  *xShutdown)(void
b700: 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e  *);      /* Dein
b710: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
b720: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
b730: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
b740: 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  a;              
b750: 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f    /* Argument to
b760: 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68   xInit() and xSh
b770: 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a  utdown() */.};..
b780: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
b790: 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
b7a0: 74 69 6f 6e 73 20 7b 48 31 30 31 36 30 7d 20 3c  tions {H10160} <
b7b0: 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S20000>.** EXPER
b7c0: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
b7d0: 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
b7e0: 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
b7f0: 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
b800: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
b810: 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
b820: 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
b830: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
b840: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
b850: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
b860: 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
b870: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
b880: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
b890: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
b8a0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
b8b0: 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
b8c0: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
b8d0: 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
b8e0: 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
b8f0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
b900: 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
b910: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
b920: 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
b930: 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
b940: 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
b950: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
b960: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
b970: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
b980: 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
b990: 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
b9a0: 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
b9b0: 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
b9c0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
b9d0: 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
b9e0: 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
b9f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
ba00: 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
ba10: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
ba20: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
ba30: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68  this option.  Th
ba40: 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c  is option disabl
ba50: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
ba60: 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
ba70: 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
ba80: 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
ba90: 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
baa0: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 3c   single thread.<
bab0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
bac0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
bad0: 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
bae0: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
baf0: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
bb00: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69  his option.  Thi
bb10: 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65  s option disable
bb20: 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e  s.** mutexing on
bb30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
bb40: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
bb50: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
bb60: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20  objects..** The 
bb70: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72  application is r
bb80: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73  esponsible for s
bb90: 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73  erializing acces
bba0: 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73  s to.** [databas
bbb0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
bbc0: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
bbd0: 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f  tements].  But o
bbe0: 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20  ther mutexes.** 
bbf0: 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74  are enabled so t
bc00: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
bc10: 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69  be safe to use i
bc20: 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
bc30: 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e  ed.** environmen
bc40: 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
bc50: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
bc60: 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
bc70: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
bc80: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
bc90: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54   this option.  T
bca0: 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
bcb0: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
bcc0: 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
bcd0: 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
bce0: 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
bcf0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
bd00: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
bd10: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
bd20: 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
bd30: 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
bd40: 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
bd50: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
bd60: 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
bd70: 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
bd80: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
bd90: 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
bda0: 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
bdb0: 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
bdc0: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
bdd0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
bde0: 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
bdf0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
be00: 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
be10: 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
be20: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
be30: 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
be40: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
be50: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
be60: 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
be70: 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 70  e time..**.** <p
be80: 3e 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74  >This configurat
be90: 69 6f 6e 20 6f 70 74 69 6f 6e 20 6d 65 72 65 6c  ion option merel
bea0: 79 20 73 65 74 73 20 74 68 65 20 64 65 66 61 75  y sets the defau
beb0: 6c 74 20 6d 75 74 65 78 20 0a 2a 2a 20 62 65 68  lt mutex .** beh
bec0: 61 76 69 6f 72 20 74 6f 20 73 65 72 69 61 6c 69  avior to seriali
bed0: 7a 65 20 61 63 63 65 73 73 20 74 6f 20 5b 64 61  ze access to [da
bee0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
bef0: 6e 73 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  ns].  Individual
bf00: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
bf10: 6e 6e 65 63 74 69 6f 6e 73 5d 20 63 61 6e 20 6f  nnections] can o
bf20: 76 65 72 72 69 64 65 20 74 68 69 73 20 73 65 74  verride this set
bf30: 74 69 6e 67 0a 2a 2a 20 75 73 69 6e 67 20 74 68  ting.** using th
bf40: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
bf50: 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 74 6f 20  OMUTEX] flag to 
bf60: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
bf70: 28 29 5d 2e 3c 2f 70 3e 3c 2f 64 64 3e 0a 2a 2a  ()].</p></dd>.**
bf80: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
bf90: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74  ONFIG_MALLOC</dt
bfa0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
bfb0: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
bfc0: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
bfd0: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
bfe0: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
bff0: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
c000: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
c010: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
c020: 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
c030: 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
c040: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
c050: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
c060: 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
c070: 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20   in place of.** 
c080: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
c090: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62  ation routines b
c0a0: 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
c0b0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
c0c0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
c0d0: 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
c0e0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
c0f0: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
c100: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
c110: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
c120: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
c130: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
c140: 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
c150: 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69  ture.  The [sqli
c160: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
c170: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
c180: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
c190: 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
c1a0: 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
c1b0: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
c1c0: 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
c1d0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
c1e0: 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
c1f0: 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
c200: 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
c210: 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
c220: 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
c230: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c240: 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
c250: 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
c260: 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
c270: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
c280: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
c290: 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
c2a0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
c2b0: 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
c2c0: 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
c2d0: 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20  nt, interpreted 
c2e0: 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e  as a .** boolean
c2f0: 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
c300: 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
c310: 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65  collection of me
c320: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c330: 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20  .** statistics. 
c340: 57 68 65 6e 20 64 69 73 61 62 6c 65 64 2c 20 74  When disabled, t
c350: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
c360: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
c370: 65 63 6f 6d 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70  ecome .** non-op
c380: 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20  erational:.**   
c390: 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  <ul>.**   <li> [
c3a0: 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
c3b0: 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  sed()].**   <li>
c3c0: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
c3d0: 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a  _highwater()].**
c3e0: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
c3f0: 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
c400: 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
c410: 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d  qlite3_status()]
c420: 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c  .**   </ul>.** <
c430: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
c440: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
c450: 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
c460: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  >This option spe
c470: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
c480: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
c490: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
c4a0: 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
c4b0: 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
c4c0: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
c4d0: 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
c4e0: 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74  to the memory, t
c4f0: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
c500: 63 68 20 73 63 72 61 74 63 68 20 62 75 66 66 65  ch scratch buffe
c510: 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
c520: 6e 75 6d 62 65 72 20 6f 66 20 62 75 66 66 65 72  number of buffer
c530: 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a  s (N).  The sz.*
c540: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
c550: 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  be a multiple of
c560: 20 31 36 2e 20 54 68 65 20 73 7a 20 70 61 72 61   16. The sz para
c570: 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20  meter should be 
c580: 61 20 66 65 77 20 62 79 74 65 73 0a 2a 2a 20 6c  a few bytes.** l
c590: 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 61  arger than the a
c5a0: 63 74 75 61 6c 20 73 63 72 61 74 63 68 20 73 70  ctual scratch sp
c5b0: 61 63 65 20 72 65 71 75 69 72 65 64 20 64 75 65  ace required due
c5c0: 20 69 6e 74 65 72 6e 61 6c 20 6f 76 65 72 68 65   internal overhe
c5d0: 61 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ad..** The first
c5e0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
c5f0: 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  uld point to an 
c600: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74  allocation of at
c610: 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
c620: 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
c630: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
c640: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  no more than one
c650: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
c660: 61 74 20 6f 6e 63 65 20 70 65 72 20 74 68 72 65  at once per thre
c670: 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75  ad, so.** N shou
c680: 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 65  ld be set to the
c690: 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75   expected maximu
c6a0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65  m number of thre
c6b0: 61 64 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20  ads.  The sz.** 
c6c0: 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64  parameter should
c6d0: 20 62 65 20 36 20 74 69 6d 65 73 20 74 68 65 20   be 6 times the 
c6e0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
c6f0: 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
c700: 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74  e size..** Scrat
c710: 63 68 20 62 75 66 66 65 72 73 20 61 72 65 20 75  ch buffers are u
c720: 73 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  sed as part of t
c730: 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65  he btree balance
c740: 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a   operation.  If.
c750: 2a 2a 20 54 68 65 20 62 74 72 65 65 20 62 61 6c  ** The btree bal
c760: 61 6e 63 65 72 20 6e 65 65 64 73 20 61 64 64 69  ancer needs addi
c770: 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65  tional memory be
c780: 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
c790: 76 69 64 65 64 20 62 79 0a 2a 2a 20 73 63 72 61  vided by.** scra
c7a0: 74 63 68 20 62 75 66 66 65 72 73 20 6f 72 20 69  tch buffers or i
c7b0: 66 20 6e 6f 20 73 63 72 61 74 63 68 20 62 75 66  f no scratch buf
c7c0: 66 65 72 20 73 70 61 63 65 20 69 73 20 73 70 65  fer space is spe
c7d0: 63 69 66 69 65 64 2c 20 74 68 65 6e 20 53 51 4c  cified, then SQL
c7e0: 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b  ite.** goes to [
c7f0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
c800: 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  ] to obtain the 
c810: 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65 64 73 2e  memory it needs.
c820: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
c830: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
c840: 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
c850: 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
c860: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
c870: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
c880: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
c890: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20   use for.** the 
c8a0: 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
c8b0: 63 68 65 2e 20 20 54 68 65 72 65 20 61 72 65 20  che.  There are 
c8c0: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
c8d0: 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   A pointer to th
c8e0: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65  e.** memory, the
c8f0: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
c900: 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20  ge buffer (sz), 
c910: 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
c920: 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20  f pages (N)..** 
c930: 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
c940: 6d 75 73 74 20 62 65 20 61 20 70 6f 77 65 72 20  must be a power 
c950: 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
c960: 31 32 20 61 6e 64 20 33 32 37 36 38 2e 20 20 54  12 and 32768.  T
c970: 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
c980: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
c990: 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
c9a0: 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  on of at least s
c9b0: 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
c9c0: 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ory..** SQLite w
c9d0: 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f  ill use the memo
c9e0: 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  ry provided by t
c9f0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
ca00: 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73  t to satisfy its
ca10: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  .** memory needs
ca20: 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e   for the first N
ca30: 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61   pages that it a
ca40: 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 49  dds to cache.  I
ca50: 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
ca60: 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
ca70: 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
ca80: 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
ca90: 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69  ded by this opti
caa0: 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  on, then.** SQLi
cab0: 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  te goes to [sqli
cac0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f  te3_malloc()] fo
cad0: 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c  r the additional
cae0: 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a   storage space..
caf0: 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** The implement
cb00: 61 74 69 6f 6e 20 6d 69 67 68 74 20 75 73 65 20  ation might use 
cb10: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
cb20: 68 65 20 4e 20 62 75 66 66 65 72 73 20 74 6f 20  he N buffers to 
cb30: 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20  hold .** memory 
cb40: 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66 6f 72  accounting infor
cb50: 6d 61 74 69 6f 6e 2e 20 3c 2f 64 64 3e 0a 2a 2a  mation. </dd>.**
cb60: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
cb70: 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
cb80: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
cb90: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
cba0: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
cbb0: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
cbc0: 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20  will use.** for 
cbd0: 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
cbe0: 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ic memory alloca
cbf0: 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e  tion needs beyon
cc00: 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
cc10: 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49  .** for by [SQLI
cc20: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
cc30: 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43  H] and [SQLITE_C
cc40: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
cc50: 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
cc60: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
cc70: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
cc80: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 6e 75 6d   memory, the num
cc90: 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
cca0: 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
ccb0: 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
ccc0: 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
ccd0: 20 73 69 7a 65 2e 20 20 49 66 0a 2a 2a 20 74 68   size.  If.** th
cce0: 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
ccf0: 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
cd00: 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
cd10: 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
cd20: 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
cd30: 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
cd40: 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
cd50: 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
cd60: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
cd70: 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
cd80: 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
cd90: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
cda0: 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66 20  IG_MALLOC].  If 
cdb0: 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f  the.** memory po
cdc0: 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
cdd0: 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51  L and either [SQ
cde0: 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
cdf0: 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  YS3] or.** [SQLI
ce00: 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
ce10: 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20  5] are defined, 
ce20: 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61  then the alterna
ce30: 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  tive memory.** a
ce40: 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61  llocator is enga
ce50: 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c  ged to handle al
ce60: 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d  l of SQLites mem
ce70: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
ce80: 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  eeds.</dd>.**.**
ce90: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
cea0: 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  IG_MUTEX</dt>.**
ceb0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
cec0: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
ced0: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
cee0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
cef0: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
cf00: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
cf10: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
cf20: 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
cf30: 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
cf40: 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
cf50: 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
cf60: 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
cf70: 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74  ed in place.** t
cf80: 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
cf90: 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
cfa0: 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ite.</dd>.**.** 
cfb0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
cfc0: 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a  G_GETMUTEX</dt>.
cfd0: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
cfe0: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
cff0: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
d000: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
d010: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
d020: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
d030: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
d040: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
d050: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
d060: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
d070: 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
d080: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
d090: 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
d0a0: 78 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54  x routines..** T
d0b0: 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
d0c0: 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
d0d0: 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
d0e0: 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  utex allocation.
d0f0: 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
d100: 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20   a wrapper used 
d110: 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75  to track mutex u
d120: 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d  sage for perform
d130: 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e  ance.** profilin
d140: 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f  g or testing, fo
d150: 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a  r example.</dd>.
d160: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
d170: 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
d180: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  E</dt>.** <dd>Th
d190: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
d1a0: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
d1b0: 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
d1c0: 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f   default.** memo
d1d0: 72 79 20 61 6c 6c 63 61 74 69 6f 6e 20 6c 6f 6f  ry allcation loo
d1e0: 6b 61 73 69 64 65 20 6f 70 74 69 6d 69 7a 61 74  kaside optimizat
d1f0: 69 6f 6e 2e 20 20 54 68 65 20 66 69 72 73 74 20  ion.  The first 
d200: 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
d210: 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
d220: 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
d230: 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65   slot and the se
d240: 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62  cond is the numb
d250: 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61  er of.** slots a
d260: 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68  llocated to each
d270: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
d280: 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
d290: 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
d2a0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d2b0: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
d2c0: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
d2d0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
d2e0: 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
d2f0: 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
d300: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
d310: 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
d320: 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
d330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
d340: 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
d350: 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
d360: 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
d370: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
d380: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
d390: 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
d3a0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
d3b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d3c0: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
d3d0: 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a       6  /* void*
d3e0: 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
d3f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d400: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
d410: 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
d420: 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
d430: 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
d440: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
d450: 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
d460: 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
d470: 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
d480: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
d490: 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
d4a0: 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
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 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
d4d0: 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
d4e0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
d4f0: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
d500: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
d510: 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
d520: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
d530: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
d540: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
d550: 48 55 4e 4b 41 4c 4c 4f 43 20 20 20 31 32 20 20  HUNKALLOC   12  
d560: 2f 2a 20 69 6e 74 20 74 68 72 65 73 68 6f 6c 64  /* int threshold
d570: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d580: 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
d590: 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
d5a0: 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a  t int */.../*.**
d5b0: 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
d5c0: 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
d5d0: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
d5e0: 65 73 20 7b 48 31 32 32 30 30 7d 20 3c 53 31 30  es {H12200} <S10
d5f0: 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  700>.**.** The s
d600: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
d610: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
d620: 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
d630: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
d640: 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
d650: 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
d660: 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 54 68 65  e of SQLite. The
d670: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
d680: 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
d690: 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
d6a0: 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
d6b0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 63   compatibility c
d6c0: 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e 0a 2a  onsiderations..*
d6d0: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
d6e0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 31 7d 20  .**.** {H12201} 
d6f0: 45 61 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61  Each new [databa
d700: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
d710: 68 61 6c 6c 20 68 61 76 65 20 74 68 65 0a 2a 2a  hall have the.**
d720: 20 20 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e            [exten
d730: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
d740: 5d 20 66 65 61 74 75 72 65 20 64 69 73 61 62 6c  ] feature disabl
d750: 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
d760: 2a 0a 2a 2a 20 7b 48 31 32 32 30 32 7d 20 54 68  *.** {H12202} Th
d770: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  e [sqlite3_exten
d780: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
d790: 28 44 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 65  (D,F)] interface
d7a0: 20 73 68 61 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a   shall enable.**
d7b0: 20 20 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e            [exten
d7c0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
d7d0: 5d 20 66 6f 72 20 74 68 65 20 20 5b 64 61 74 61  ] for the  [data
d7e0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
d7f0: 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69   D.**          i
d800: 66 20 74 68 65 20 46 20 70 61 72 61 6d 65 74 65  f the F paramete
d810: 72 20 69 73 20 74 72 75 65 2c 20 6f 72 20 64 69  r is true, or di
d820: 73 61 62 6c 65 20 74 68 65 6d 20 69 66 20 46 20  sable them if F 
d830: 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74  is false..*/.int
d840: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
d850: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
d860: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
d870: 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
d880: 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
d890: 74 20 52 6f 77 69 64 20 7b 48 31 32 32 32 30 7d  t Rowid {H12220}
d8a0: 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10700>.**.** 
d8b0: 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e  Each entry in an
d8c0: 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61   SQLite table ha
d8d0: 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
d8e0: 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
d8f0: 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
d900: 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68 65 20  he "rowid". The 
d910: 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
d920: 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
d930: 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
d940: 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
d950: 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
d960: 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
d970: 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
d980: 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
d990: 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
d9a0: 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66  ared columns. If
d9b0: 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
d9c0: 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
d9d0: 70 65 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41  pe INTEGER PRIMA
d9e0: 52 59 20 4b 45 59 20 74 68 65 6e 20 74 68 61 74  RY KEY then that
d9f0: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
da00: 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
da10: 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
da20: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
da30: 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64 20  turns the rowid 
da40: 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  of the most rece
da50: 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  nt.** successful
da60: 20 49 4e 53 45 52 54 20 69 6e 74 6f 20 74 68 65   INSERT into the
da70: 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74   database from t
da80: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
da90: 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74  nection].** in t
daa0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
dab0: 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73  t.  If no succes
dac0: 73 66 75 6c 20 49 4e 53 45 52 54 73 0a 2a 2a 20  sful INSERTs.** 
dad0: 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
dae0: 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62  ed on that datab
daf0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
db00: 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
db10: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e  ..**.** If an IN
db20: 53 45 52 54 20 6f 63 63 75 72 73 20 77 69 74 68  SERT occurs with
db30: 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68  in a trigger, th
db40: 65 6e 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  en the rowid of 
db50: 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20  the inserted.** 
db60: 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20  row is returned 
db70: 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
db80: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
db90: 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e  rigger is runnin
dba0: 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
dbb0: 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69  he trigger termi
dbc0: 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65  nates, the value
dbd0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
dbe0: 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76  s routine.** rev
dbf0: 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74  erts to the last
dc00: 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20   value inserted 
dc10: 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
dc20: 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  er fired..**.** 
dc30: 41 6e 20 49 4e 53 45 52 54 20 74 68 61 74 20 66  An INSERT that f
dc40: 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
dc50: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
dc60: 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
dc70: 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54  uccessful INSERT
dc80: 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
dc90: 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
dca0: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
dcb0: 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75  ** routine.  Thu
dcc0: 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
dcd0: 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
dce0: 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
dcf0: 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
dd00: 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
dd10: 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
dd20: 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
dd30: 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
dd40: 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
dd50: 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
dd60: 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f  .  When INSERT O
dd70: 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
dd80: 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
dd90: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
dda0: 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
ddb0: 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
ddc0: 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
ddd0: 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
dde0: 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
ddf0: 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
de00: 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
de10: 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
de20: 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
de30: 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
de40: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
de50: 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
de60: 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20  ..**.** For the 
de70: 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
de80: 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 49 4e 53   routine, an INS
de90: 45 52 54 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ERT is considere
dea0: 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
deb0: 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
dec0: 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
ded0: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
dee0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
def0: 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32 31 7d 20 54  **.** {H12221} T
df00: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
df10: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
df20: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
df30: 73 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 20  s the rowid.**  
df40: 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6d          of the m
df50: 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65  ost recent succe
df60: 73 73 66 75 6c 20 49 4e 53 45 52 54 20 70 65 72  ssful INSERT per
df70: 66 6f 72 6d 65 64 20 6f 6e 20 74 68 65 20 73 61  formed on the sa
df80: 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  me.**          [
df90: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
dfa0: 69 6f 6e 5d 20 61 6e 64 20 77 69 74 68 69 6e 20  ion] and within 
dfb0: 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68  the same or high
dfc0: 65 72 20 6c 65 76 65 6c 0a 2a 2a 20 20 20 20 20  er level.**     
dfd0: 20 20 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e       trigger con
dfe0: 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66  text, or zero if
dff0: 20 74 68 65 72 65 20 68 61 76 65 20 62 65 65 6e   there have been
e000: 20 6e 6f 20 71 75 61 6c 69 66 79 69 6e 67 20 69   no qualifying i
e010: 6e 73 65 72 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nserts..**.** {H
e020: 31 32 32 32 33 7d 20 54 68 65 20 5b 73 71 6c 69  12223} The [sqli
e030: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
e040: 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f  rowid()] functio
e050: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  n returns the.**
e060: 20 20 20 20 20 20 20 20 20 20 73 61 6d 65 20 76            same v
e070: 61 6c 75 65 20 77 68 65 6e 20 63 61 6c 6c 65 64  alue when called
e080: 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
e090: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 0a 2a  rigger context.*
e0a0: 2a 20 20 20 20 20 20 20 20 20 20 69 6d 6d 65 64  *          immed
e0b0: 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 61 6e  iately before an
e0c0: 64 20 61 66 74 65 72 20 61 20 52 4f 4c 4c 42 41  d after a ROLLBA
e0d0: 43 4b 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50  CK..**.** ASSUMP
e0e0: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
e0f0: 32 32 33 32 7d 20 49 66 20 61 20 73 65 70 61 72  2232} If a separ
e100: 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
e110: 72 6d 73 20 61 20 6e 65 77 20 49 4e 53 45 52 54  rms a new INSERT
e120: 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
e130: 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73           databas
e140: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
e150: 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
e160: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
e170: 64 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  d()].**         
e180: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
e190: 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
e1a0: 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
e1b0: 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a 2a 20  nsert rowid,.** 
e1c0: 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68           then th
e1d0: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
e1e0: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
e1f0: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
e200: 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] is.**         
e210: 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
e220: 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
e230: 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
e240: 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
e250: 20 20 20 20 20 20 20 20 20 6c 61 73 74 20 69 6e           last in
e260: 73 65 72 74 20 72 6f 77 69 64 2e 0a 2a 2f 0a 73  sert rowid..*/.s
e270: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
e280: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
e290: 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
e2a0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
e2b0: 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
e2c0: 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
e2d0: 66 69 65 64 20 7b 48 31 32 32 34 30 7d 20 3c 53  fied {H12240} <S
e2e0: 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  10600>.**.** Thi
e2f0: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
e300: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
e310: 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74   database rows t
e320: 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64  hat were changed
e330: 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20  .** or inserted 
e340: 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  or deleted by th
e350: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
e360: 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74  completed SQL st
e370: 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68  atement.** on th
e380: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
e390: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
e3a0: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70  d by the first p
e3b0: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c  arameter..** Onl
e3c0: 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  y changes that a
e3d0: 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
e3e0: 69 66 69 65 64 20 62 79 20 74 68 65 20 49 4e 53  ified by the INS
e3f0: 45 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a 20  ERT, UPDATE,.** 
e400: 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
e410: 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ent are counted.
e420: 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e    Auxiliary chan
e430: 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a  ges caused by.**
e440: 20 74 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f   triggers are no
e450: 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65 20 74  t counted. Use t
e460: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
e470: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  l_changes()] fun
e480: 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64  ction.** to find
e490: 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
e4a0: 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 63  r of changes inc
e4b0: 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63  luding changes c
e4c0: 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72  aused by trigger
e4d0: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77 20  s..**.** A "row 
e4e0: 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61  change" is a cha
e4f0: 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20  nge to a single 
e500: 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  row of a single 
e510: 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20  table.** caused 
e520: 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45  by an INSERT, DE
e530: 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20  LETE, or UPDATE 
e540: 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73  statement.  Rows
e550: 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61   that.** are cha
e560: 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66  nged as side eff
e570: 65 63 74 73 20 6f 66 20 52 45 50 4c 41 43 45 20  ects of REPLACE 
e580: 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
e590: 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61  ution,.** rollba
e5a0: 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73  ck, ABORT proces
e5b0: 73 69 6e 67 2c 20 44 52 4f 50 20 54 41 42 4c 45  sing, DROP TABLE
e5c0: 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65  , or by any othe
e5d0: 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20  r.** mechanisms 
e5e0: 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
e5f0: 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
e600: 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69  es..**.** A "tri
e610: 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73  gger context" is
e620: 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63   a scope of exec
e630: 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e  ution that begin
e640: 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69  s and.** ends wi
e650: 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66  th the script of
e660: 20 61 20 74 72 69 67 67 65 72 2e 20 20 4d 6f 73   a trigger.  Mos
e670: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
e680: 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65   are.** evaluate
e690: 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79  d outside of any
e6a0: 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 20   trigger.  This 
e6b0: 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65  is the "top leve
e6c0: 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  l".** trigger co
e6d0: 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 69  ntext.  If a tri
e6e0: 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20  gger fires from 
e6f0: 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61  the top level, a
e700: 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20  .** new trigger 
e710: 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72  context is enter
e720: 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74  ed for the durat
e730: 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a  ion of that one.
e740: 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 62  ** trigger.  Sub
e750: 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65 20  triggers create 
e760: 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20  subcontexts for 
e770: 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a  their duration..
e780: 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b 73  **.** Calling [s
e790: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f  qlite3_exec()] o
e7a0: 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
e7b0: 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64  )] recursively d
e7c0: 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74  oes.** not creat
e7d0: 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20  e a new trigger 
e7e0: 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54  context..**.** T
e7f0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
e800: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
e810: 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  of direct row ch
e820: 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20  anges in the.** 
e830: 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
e840: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
e850: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
e860: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a  within the same.
e870: 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
e880: 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73 2c 20  xt..**.** Thus, 
e890: 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d  when called from
e8a0: 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
e8b0: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
e8c0: 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  turns the.** num
e8d0: 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69  ber of changes i
e8e0: 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
e8f0: 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
e900: 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
e910: 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65  hat also occurre
e920: 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76  d at the top lev
e930: 65 6c 2e 20 20 57 69 74 68 69 6e 20 74 68 65 20  el.  Within the 
e940: 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65  body of a trigge
e950: 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  r,.** the sqlite
e960: 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65  3_changes() inte
e970: 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c  rface can be cal
e980: 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  led to find the 
e990: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
e9a0: 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
e9b0: 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
e9c0: 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
e9d0: 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
e9e0: 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
e9f0: 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68  n the body of th
ea00: 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
ea10: 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
ea20: 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20  number returned 
ea30: 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
ea40: 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73   changes.** caus
ea50: 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72  ed by subtrigger
ea60: 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61  s since those ha
ea70: 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e  ve their own con
ea80: 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  text..**.** SQLi
ea90: 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
eaa0: 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54  e command "DELET
eab0: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69  E FROM table" wi
eac0: 74 68 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c  thout a WHERE cl
ead0: 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70  ause.** by dropp
eae0: 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69  ing and recreati
eaf0: 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28  ng the table.  (
eb00: 54 68 69 73 20 69 73 20 6d 75 63 68 20 66 61 73  This is much fas
eb10: 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a  ter than going.*
eb20: 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65  * through and de
eb30: 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61  leting individua
eb40: 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20  l elements from 
eb50: 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63  the table.)  Bec
eb60: 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  ause of this.** 
eb70: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68  optimization, th
eb80: 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22  e deletions in "
eb90: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
eba0: 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63  e" are not row c
ebb0: 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69  hanges and.** wi
ebc0: 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65  ll not be counte
ebd0: 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
ebe0: 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73  _changes() or [s
ebf0: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
ec00: 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  nges()].** funct
ec10: 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 73  ions, regardless
ec20: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
ec30: 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20  f elements that 
ec40: 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  were originally.
ec50: 2a 2a 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e  ** in the table.
ec60: 20 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75    To get an accu
ec70: 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68  rate count of th
ec80: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
ec90: 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a   deleted, use.**
eca0: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
ecb0: 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73  ble WHERE 1" ins
ecc0: 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  tead..**.** INVA
ecd0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
ece0: 31 32 32 34 31 7d 20 54 68 65 20 5b 73 71 6c 69  12241} The [sqli
ecf0: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  te3_changes()] f
ed00: 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65  unction shall re
ed10: 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
ed20: 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  of.**          r
ed30: 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ow changes cause
ed40: 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
ed50: 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
ed60: 41 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ATE,.**         
ed70: 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
ed80: 6d 65 6e 74 20 6f 6e 20 74 68 65 20 73 61 6d 65  ment on the same
ed90: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
eda0: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20  tion and.**     
edb0: 20 20 20 20 20 77 69 74 68 69 6e 20 74 68 65 20       within the 
edc0: 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72 20 74  same or higher t
edd0: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20  rigger context, 
ede0: 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65  or zero if there
edf0: 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20   have.**        
ee00: 20 20 6e 6f 74 20 62 65 65 6e 20 61 6e 79 20 71    not been any q
ee10: 75 61 6c 69 66 79 69 6e 67 20 72 6f 77 20 63 68  ualifying row ch
ee20: 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  anges..**.** {H1
ee30: 32 32 34 33 7d 20 53 74 61 74 65 6d 65 6e 74 73  2243} Statements
ee40: 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45   of the form "DE
ee50: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e  LETE FROM tablen
ee60: 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20  ame" with no.** 
ee70: 20 20 20 20 20 20 20 20 20 57 48 45 52 45 20 63           WHERE c
ee80: 6c 61 75 73 65 20 73 68 61 6c 6c 20 63 61 75 73  lause shall caus
ee90: 65 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  e subsequent cal
eea0: 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ls to.**        
eeb0: 20 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67    [sqlite3_chang
eec0: 65 73 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20  es()] to return 
eed0: 7a 65 72 6f 2c 20 72 65 67 61 72 64 6c 65 73 73  zero, regardless
eee0: 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
eef0: 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f      number of ro
ef00: 77 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e  ws originally in
ef10: 20 74 68 65 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a   the table..**.*
ef20: 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a  * ASSUMPTIONS:.*
ef30: 2a 0a 2a 2a 20 7b 41 31 32 32 35 32 7d 20 49 66  *.** {A12252} If
ef40: 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
ef50: 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
ef60: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
ef70: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ef80: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69  .**          whi
ef90: 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
efa0: 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
efb0: 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
efc0: 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20   returned.**    
efd0: 20 20 20 20 20 20 69 73 20 75 6e 70 72 65 64 69        is unpredi
efe0: 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
eff0: 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
f000: 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
f010: 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
f020: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
f030: 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
f040: 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32  ws Modified {H12
f050: 32 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a  260} <S10600>.**
f060: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
f070: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
f080: 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
f090: 67 65 73 20 63 61 75 73 65 64 20 62 79 20 49 4e  ges caused by IN
f0a0: 53 45 52 54 2c 0a 2a 2a 20 55 50 44 41 54 45 20  SERT,.** UPDATE 
f0b0: 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
f0c0: 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b  ents since the [
f0d0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f0e0: 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e  ion] was opened.
f0f0: 0a 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20 69 6e  .** The count in
f100: 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67  cludes all chang
f110: 65 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72 69 67  es from all trig
f120: 67 65 72 20 63 6f 6e 74 65 78 74 73 2e 20 20 48  ger contexts.  H
f130: 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63  owever,.** the c
f140: 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
f150: 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73  clude changes us
f160: 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
f170: 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69  REPLACE constrai
f180: 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62  nts,.** do rollb
f190: 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72  acks or ABORT pr
f1a0: 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 44 52 4f  ocessing, or DRO
f1b0: 50 20 74 61 62 6c 65 20 70 72 6f 63 65 73 73 69  P table processi
f1c0: 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67  ng..** The chang
f1d0: 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61  es are counted a
f1e0: 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74  s soon as the st
f1f0: 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b  atement that mak
f200: 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f  es them is.** co
f210: 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
f220: 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
f230: 6c 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 20  le is passed to 
f240: 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
f250: 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
f260: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
f270: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c  *.** SQLite impl
f280: 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61  ements the comma
f290: 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  nd "DELETE FROM 
f2a0: 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61  table" without a
f2b0: 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a   WHERE clause.**
f2c0: 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64   by dropping and
f2d0: 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20   recreating the 
f2e0: 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73  table.  (This is
f2f0: 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61   much faster tha
f300: 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75  n going.** throu
f310: 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20  gh and deleting 
f320: 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65  individual eleme
f330: 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62  nts from the tab
f340: 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66  le.)  Because of
f350: 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a   this.** optimiz
f360: 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74  ation, the delet
f370: 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20  ions in "DELETE 
f380: 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20  FROM table" are 
f390: 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  not row changes 
f3a0: 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  and.** will not 
f3b0: 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68  be counted by th
f3c0: 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
f3d0: 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  s() or [sqlite3_
f3e0: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
f3f0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72  .** functions, r
f400: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
f410: 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65   number of eleme
f420: 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72  nts that were or
f430: 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74  iginally.** in t
f440: 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65  he table.  To ge
f450: 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f  t an accurate co
f460: 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  unt of the numbe
f470: 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65  r of rows delete
f480: 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54  d, use.** "DELET
f490: 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45  E FROM table WHE
f4a0: 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a  RE 1" instead..*
f4b0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
f4c0: 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
f4d0: 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  es()] interface.
f4e0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
f4f0: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 31  S:.**.** {H12261
f500: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  } The [sqlite3_t
f510: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
f520: 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61  returns the tota
f530: 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20  l number.**     
f540: 20 20 20 20 20 6f 66 20 72 6f 77 20 63 68 61 6e       of row chan
f550: 67 65 73 20 63 61 75 73 65 64 20 62 79 20 49 4e  ges caused by IN
f560: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 61 6e  SERT, UPDATE, an
f570: 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 20  d/or DELETE.**  
f580: 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e          statemen
f590: 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ts on the same [
f5a0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f5b0: 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20  ion], in any.** 
f5c0: 20 20 20 20 20 20 20 20 20 74 72 69 67 67 65 72           trigger
f5d0: 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63 65 20   context, since 
f5e0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
f5f0: 6e 65 63 74 69 6f 6e 20 77 61 73 20 63 72 65 61  nection was crea
f600: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  ted..**.** {H122
f610: 36 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f  63} Statements o
f620: 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45  f the form "DELE
f630: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d  TE FROM tablenam
f640: 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20  e" with no.**   
f650: 20 20 20 20 20 20 20 57 48 45 52 45 20 63 6c 61         WHERE cla
f660: 75 73 65 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68  use shall not ch
f670: 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
f680: 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20  eturned.**      
f690: 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f      by [sqlite3_
f6a0: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
f6b0: 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49  ..**.** ASSUMPTI
f6c0: 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32  ONS:.**.** {A122
f6d0: 36 34 7d 20 49 66 20 61 20 73 65 70 61 72 61 74  64} If a separat
f6e0: 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
f6f0: 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
f700: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
f710: 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
f720: 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65     while [sqlite
f730: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
f740: 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
f750: 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
f760: 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 65           returne
f770: 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
f780: 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
f790: 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
f7a0: 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
f7b0: 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
f7c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f7d0: 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
f7e0: 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b  -Running Query {
f7f0: 48 31 32 32 37 30 7d 20 3c 53 33 30 35 30 30 3e  H12270} <S30500>
f800: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
f810: 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
f820: 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
f830: 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
f840: 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
f850: 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
f860: 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
f870: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
f880: 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
f890: 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
f8a0: 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
f8b0: 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
f8c0: 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
f8d0: 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
f8e0: 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
f8f0: 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
f900: 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
f910: 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
f920: 20 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63   It is safe to c
f930: 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
f940: 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
f950: 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
f960: 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
f970: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
f980: 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
f990: 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
f9a0: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
f9b0: 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
f9c0: 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
f9d0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
f9e0: 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
f9f0: 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
fa00: 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
fa10: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
fa20: 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
fa30: 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72  * If an SQL oper
fa40: 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
fa50: 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
fa60: 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
fa70: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
fa80: 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
fa90: 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
faa0: 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
fab0: 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
fac0: 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
fad0: 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
fae0: 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
faf0: 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61  .** An SQL opera
fb00: 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
fb10: 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
fb20: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
fb30: 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74  ERRUPT]..** If t
fb40: 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
fb50: 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
fb60: 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
fb70: 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
fb80: 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
fb90: 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
fba0: 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
fbb0: 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
fbc0: 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
fbd0: 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
fbe0: 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
fbf0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
fc00: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 68 61  3_interrupt() ha
fc10: 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
fc20: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
fc30: 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
fc40: 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
fc50: 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
fc60: 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  rns..**.** INVAR
fc70: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
fc80: 32 32 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2271} The [sqlit
fc90: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20  e3_interrupt()] 
fca0: 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 66  interface will f
fcb0: 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e 69 6e 67  orce all running
fcc0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
fcd0: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
fce0: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
fcf0: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
fd00: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
fd10: 20 20 20 20 20 74 6f 20 68 61 6c 74 20 61 66 74       to halt aft
fd20: 65 72 20 70 72 6f 63 65 73 73 69 6e 67 20 61 74  er processing at
fd30: 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64 69 74 69   most one additi
fd40: 6f 6e 61 6c 20 72 6f 77 20 6f 66 20 64 61 74 61  onal row of data
fd50: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 32 7d  ..**.** {H12272}
fd60: 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65   Any SQL stateme
fd70: 6e 74 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  nt that is inter
fd80: 72 75 70 74 65 64 20 62 79 20 5b 73 71 6c 69 74  rupted by [sqlit
fd90: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
fda0: 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c  **          will
fdb0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
fdc0: 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a  INTERRUPT]..**.*
fdd0: 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a  * ASSUMPTIONS:.*
fde0: 2a 0a 2a 2a 20 7b 41 31 32 32 37 39 7d 20 49 66  *.** {A12279} If
fdf0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
fe00: 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
fe10: 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
fe20: 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20  nterrupt()].**  
fe30: 20 20 20 20 20 20 20 20 69 73 20 72 75 6e 6e 69          is runni
fe40: 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
fe50: 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
fe60: 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73  appen..*/.void s
fe70: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
fe80: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
fe90: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
fea0: 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
feb0: 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
fec0: 6d 70 6c 65 74 65 20 7b 48 31 30 35 31 30 7d 20  mplete {H10510} 
fed0: 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S70200>.**.** T
fee0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
fef0: 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d  e useful for com
ff00: 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
ff10: 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
ff20: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
ff30: 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
ff40: 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d 70  ems to form comp
ff50: 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61 74 65  lete a SQL state
ff60: 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
ff70: 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
ff80: 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
ff90: 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
ffa0: 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
ffb0: 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 54 68  for parsing.  Th
ffc0: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
ffd0: 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20  urn true if the 
ffe0: 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
fff0: 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
10000 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
10010 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 65  tement.  A state
10020 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
10030 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
10040 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
10050 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
10060 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
10070 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a  fragment of a.**
10080 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
10090 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d 69  statement.  Semi
100a0 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
100b0 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
100c0 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
100d0 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
100e0 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
100f0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
10100 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
10110 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
10120 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
10130 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
10140 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
10150 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
10160 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
10170 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
10180 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  or..**.** These 
10190 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
101a0 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
101b0 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
101c0 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
101d0 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
101e0 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
101f0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
10200 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 31 7d 20 41  **.** {H10511} A
10210 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 61 6c   successful eval
10220 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  uation of [sqlit
10230 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f  e3_complete()] o
10240 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
10250 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
10260 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73 20 73  6()] functions s
10270 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  hall.**         
10280 20 72 65 74 75 72 6e 20 61 20 6e 75 6d 65 72 69   return a numeri
10290 63 20 31 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  c 1 if and only 
102a0 69 66 20 74 68 65 20 6c 61 73 74 20 6e 6f 6e 2d  if the last non-
102b0 77 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 20 20  whitespace.**   
102c0 20 20 20 20 20 20 20 74 6f 6b 65 6e 20 69 6e 20         token in 
102d0 74 68 65 69 72 20 69 6e 70 75 74 20 69 73 20 61  their input is a
102e0 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 74 20   semicolon that 
102f0 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77 65 65  is not in betwee
10300 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
10310 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e 44 20  e BEGIN and END 
10320 6f 66 20 61 20 43 52 45 41 54 45 20 54 52 49 47  of a CREATE TRIG
10330 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  GER statement..*
10340 2a 0a 2a 2a 20 7b 48 31 30 35 31 32 7d 20 49 66  *.** {H10512} If
10350 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
10360 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
10370 73 20 64 75 72 69 6e 67 20 61 6e 20 69 6e 76 6f  s during an invo
10380 63 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  cation.**       
10390 20 20 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63     of [sqlite3_c
103a0 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 20 5b 73  omplete()] or [s
103b0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
103c0 36 28 29 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  6()] then the.**
103d0 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e            routin
103e0 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b  e shall return [
103f0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
10400 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
10410 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 32 7d  :.**.** {A10512}
10420 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
10430 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
10440 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
10450 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
10460 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73           UTF-8 s
10470 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31  tring..**.** {A1
10480 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75 74 20  0513} The input 
10490 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
104a0 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
104b0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
104c0 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
104d0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
104e0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
104f0 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
10500 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
10510 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
10520 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
10530 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
10540 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
10550 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
10560 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
10570 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
10580 59 20 45 72 72 6f 72 73 20 7b 48 31 32 33 31 30  Y Errors {H12310
10590 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <S40400>.**.**
105a0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65   This routine se
105b0 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
105c0 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68  nction that migh
105d0 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  t be invoked whe
105e0 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65  never.** an atte
105f0 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  mpt is made to o
10600 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74  pen a database t
10610 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65  able that anothe
10620 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
10630 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65  rocess has locke
10640 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
10650 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
10660 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
10670 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
10680 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
10690 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ED].** is return
106a0 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
106b0 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
106c0 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20 74 68   the lock. If th
106d0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
106e0 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
106f0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
10700 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  k will be invoke
10710 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
10720 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
10730 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
10740 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73  o the handler is
10750 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
10760 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
10770 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
10780 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
10790 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
107a0 6c 65 72 28 29 2e 20 20 54 68 65 20 73 65 63 6f  ler().  The seco
107b0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
107c0 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 63 61  * the handler ca
107d0 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
107e0 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
107f0 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
10800 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
10810 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73  invoked for this
10820 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
10830 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20   If the.** busy 
10840 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
10850 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
10860 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
10870 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
10880 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
10890 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
108a0 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
108b0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
108c0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49  s returned..** I
108d0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
108e0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
108f0 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
10900 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
10910 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
10920 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e  abase for readin
10930 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  g and the cycle 
10940 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
10950 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
10960 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
10970 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
10980 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
10990 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
109a0 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
109b0 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20 53 51  ontention. If SQ
109c0 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
109d0 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
109e0 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
109f0 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
10a00 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
10a10 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
10a20 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
10a30 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53  E_BUSY].** or [S
10a40 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
10a50 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20  KED] instead of 
10a60 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
10a70 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
10a80 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
10a90 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
10aa0 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
10ab0 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
10ac0 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
10ad0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
10ae0 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
10af0 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
10b00 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
10b10 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
10b20 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
10b30 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
10b40 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
10b50 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
10b60 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
10b70 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
10b80 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
10b90 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
10ba0 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
10bb0 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
10bc0 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
10bd0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
10be0 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
10bf0 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
10c00 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
10c10 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
10c20 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
10c30 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
10c40 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
10c50 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
10c60 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
10c70 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
10c80 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
10c90 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
10ca0 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
10cb0 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
10cc0 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
10cd0 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
10ce0 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
10cf0 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  oceed..**.** The
10d00 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
10d10 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
10d20 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
10d30 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73  E_BUSY] error is
10d40 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53   converted to [S
10d50 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
10d60 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  KED].** when SQL
10d70 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69  ite is in the mi
10d80 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20  ddle of a large 
10d90 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72  transaction wher
10da0 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61  e all the.** cha
10db0 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69  nges will not fi
10dc0 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65  t into the in-me
10dd0 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c  mory cache.  SQL
10de0 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65  ite will.** alre
10df0 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52  ady hold a RESER
10e00 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  VED lock on the 
10e10 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62  database file, b
10e20 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74  ut it needs.** t
10e30 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c  o promote this l
10e40 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45  ock to EXCLUSIVE
10e50 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20   so that it can 
10e60 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70  spill cache.** p
10e70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61  ages into the da
10e80 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68  tabase file with
10e90 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63  out harm to conc
10ea0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72  urrent.** reader
10eb0 73 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e 61  s.  If it is una
10ec0 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
10ed0 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
10ee0 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
10ef0 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
10f00 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
10f10 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
10f20 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
10f30 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
10f40 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
10f50 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
10f60 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
10f70 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
10f80 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
10f90 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72  CKED].  This err
10fa0 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f  or code promotio
10fb0 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61  n.** forces an a
10fc0 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63  utomatic rollbac
10fd0 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73  k of the changes
10fe0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61  .  See the.** <a
10ff0 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f   href="/cvstrac/
11000 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f  wiki?p=Corruptio
11010 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
11020 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74  ror">.** Corrupt
11030 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
11040 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70  Error</a> wiki p
11050 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73  age for a discus
11060 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74  sion of why.** t
11070 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74  his is important
11080 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61  ..**.** There ca
11090 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
110a0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
110b0 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
110c0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
110d0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
110e0 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
110f0 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
11100 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
11110 73 65 74 20 68 61 6e 64 6c 65 72 2e 20 20 4e 6f  set handler.  No
11120 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
11130 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
11140 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c  meout()].** will
11150 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65   also set or cle
11160 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ar the busy hand
11170 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ler..**.** INVAR
11180 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
11190 32 33 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2311} The [sqlit
111a0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
111b0 44 2c 43 2c 41 29 5d 20 66 75 6e 63 74 69 6f 6e  D,C,A)] function
111c0 20 73 68 61 6c 6c 20 72 65 70 6c 61 63 65 0a 2a   shall replace.*
111d0 2a 20 20 20 20 20 20 20 20 20 20 62 75 73 79 20  *          busy 
111e0 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65 20  callback in the 
111f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11200 74 69 6f 6e 5d 20 44 20 77 69 74 68 20 61 20 6e  tion] D with a n
11210 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ew.**          a
11220 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
11230 72 20 43 20 61 6e 64 20 61 70 70 6c 69 63 61 74  r C and applicat
11240 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
11250 20 41 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31   A..**.** {H1231
11260 32 7d 20 4e 65 77 6c 79 20 63 72 65 61 74 65 64  2} Newly created
11270 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11280 63 74 69 6f 6e 73 5d 20 73 68 61 6c 6c 20 68 61  ctions] shall ha
11290 76 65 20 61 20 62 75 73 79 0a 2a 2a 20 20 20 20  ve a busy.**    
112a0 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20 6f 66        handler of
112b0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   NULL..**.** {H1
112c0 32 33 31 34 7d 20 57 68 65 6e 20 74 77 6f 20 6f  2314} When two o
112d0 72 20 6d 6f 72 65 20 5b 64 61 74 61 62 61 73 65  r more [database
112e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 73 68   connections] sh
112f0 61 72 65 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  are a.**        
11300 20 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c    [sqlite3_enabl
11310 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 20 7c  e_shared_cache |
11320 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d 2c 0a   common cache],.
11330 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
11340 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
11350 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
11360 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 6e 74  nnection current
11370 6c 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ly using.**     
11380 20 20 20 20 20 74 68 65 20 63 61 63 68 65 20 73       the cache s
11390 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20  hall be invoked 
113a0 77 68 65 6e 20 74 68 65 20 63 61 63 68 65 20 65  when the cache e
113b0 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f 63 6b  ncounters a lock
113c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 36 7d  ..**.** {H12316}
113d0 20 49 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   If a busy handl
113e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
113f0 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74  rns zero, then t
11400 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  he SQLite interf
11410 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ace.**          
11420 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68  that provoked th
11430 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 20  e locking event 
11440 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51  shall return [SQ
11450 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
11460 2a 20 7b 48 31 32 33 31 38 7d 20 53 51 4c 69 74  * {H12318} SQLit
11470 65 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 73 20  e shall invokes 
11480 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
11490 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
114a0 6e 74 73 20 77 68 69 63 68 0a 2a 2a 20 20 20 20  nts which.**    
114b0 20 20 20 20 20 20 61 72 65 20 61 20 63 6f 70 79        are a copy
114c0 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65 72 20   of the pointer 
114d0 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20  supplied by the 
114e0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
114f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
11500 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
11510 65 72 28 29 5d 20 61 6e 64 20 61 20 63 6f 75 6e  er()] and a coun
11520 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  t of the number 
11530 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20  of prior.**     
11540 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 73       invocations
11550 20 6f 66 20 74 68 65 20 62 75 73 79 20 68 61 6e   of the busy han
11560 64 6c 65 72 20 66 6f 72 20 74 68 65 20 73 61 6d  dler for the sam
11570 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  e locking event.
11580 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f  .**.** ASSUMPTIO
11590 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 33 31  NS:.**.** {A1231
115a0 39 7d 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  9} A busy handle
115b0 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
115c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
115d0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
115e0 20 20 20 20 20 6f 72 20 5b 70 72 65 70 61 72 65       or [prepare
115f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
11600 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
11610 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
11620 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
11630 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
11640 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
11650 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
11660 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
11670 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
11680 20 7b 48 31 32 33 34 30 7d 20 3c 53 34 30 34 31   {H12340} <S4041
11690 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
116a0 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
116b0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
116c0 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
116d0 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
116e0 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
116f0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
11700 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
11710 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61   locked.  The ha
11720 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
11730 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
11740 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
11750 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
11760 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
11770 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
11780 74 65 64 2e 20 7b 48 31 32 33 34 33 7d 20 41 66  ted. {H12343} Af
11790 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ter "ms" millise
117a0 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
117b0 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  g,.** the handle
117c0 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
117d0 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  h causes [sqlite
117e0 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
117f0 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  urn.** [SQLITE_B
11800 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
11810 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a  IOERR_BLOCKED]..
11820 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68  **.** Calling th
11830 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
11840 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73  an argument less
11850 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
11860 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20  o zero.** turns 
11870 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e  off all busy han
11880 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dlers..**.** The
11890 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
118a0 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
118b0 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
118c0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
118d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
118e0 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  ny any given mom
118f0 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
11900 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
11910 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
11920 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
11930 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
11940 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
11950 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
11960 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
11970 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
11980 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  red..**.** INVAR
11990 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
119a0 32 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2341} The [sqlit
119b0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
119c0 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c  )] function shal
119d0 6c 20 6f 76 65 72 72 69 64 65 20 61 6e 79 20 70  l override any p
119e0 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rior.**         
119f0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
11a00 69 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73 71  imeout()] or [sq
11a10 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
11a20 65 72 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a 2a  er()] setting.**
11a30 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65            on the
11a40 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
11a50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  connection]..**.
11a60 2a 2a 20 7b 48 31 32 33 34 33 7d 20 49 66 20 74  ** {H12343} If t
11a70 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
11a80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73   to [sqlite3_bus
11a90 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20  y_timeout()] is 
11aa0 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20  less than.**    
11ab0 20 20 20 20 20 20 6f 72 20 65 71 75 61 6c 20 74        or equal t
11ac0 6f 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  o zero, then the
11ad0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68   busy handler sh
11ae0 61 6c 6c 20 62 65 20 63 6c 65 61 72 65 64 20 73  all be cleared s
11af0 6f 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20  o that.**       
11b00 20 20 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e     all subsequen
11b10 74 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 73  t locking events
11b20 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74   immediately ret
11b30 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
11b40 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 34  ]..**.** {H12344
11b50 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 72  } If the 2nd par
11b60 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
11b70 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
11b80 29 5d 20 69 73 20 61 20 70 6f 73 69 74 69 76 65  )] is a positive
11b90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
11ba0 62 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 75  ber N, then a bu
11bb0 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c  sy handler shall
11bc0 20 62 65 20 73 65 74 20 74 68 61 74 20 72 65 70   be set that rep
11bd0 65 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a  eatedly calls.**
11be0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 78 53            the xS
11bf0 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 69 6e  leep() method in
11c00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
11c10 73 20 7c 20 56 46 53 20 69 6e 74 65 72 66 61 63  s | VFS interfac
11c20 65 5d 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20  e] until.**     
11c30 20 20 20 20 20 65 69 74 68 65 72 20 74 68 65 20       either the 
11c40 6c 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72 20 75  lock clears or u
11c50 6e 74 69 6c 20 74 68 65 20 63 75 6d 75 6c 61 74  ntil the cumulat
11c60 69 76 65 20 73 6c 65 65 70 20 74 69 6d 65 0a 2a  ive sleep time.*
11c70 2a 20 20 20 20 20 20 20 20 20 20 72 65 70 6f 72  *          repor
11c80 74 65 64 20 62 61 63 6b 20 62 79 20 78 53 6c 65  ted back by xSle
11c90 65 70 28 29 20 65 78 63 65 65 64 73 20 4e 20 6d  ep() exceeds N m
11ca0 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a  illiseconds..*/.
11cb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
11cc0 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
11cd0 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
11ce0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
11cf0 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
11d00 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
11d10 65 72 69 65 73 20 7b 48 31 32 33 37 30 7d 20 3c  eries {H12370} <
11d20 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 65  S10000>.**.** De
11d30 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
11d40 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
11d50 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
11d60 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
11d70 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
11d80 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
11d90 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
11da0 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
11db0 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
11dc0 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
11dd0 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
11de0 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
11df0 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
11e00 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
11e10 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
11e20 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
11e30 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
11e40 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
11e50 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
11e60 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
11e70 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
11e80 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
11e90 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
11ea0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
11eb0 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
11ec0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
11ed0 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
11ee0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
11ef0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
11f00 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
11f10 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
11f20 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
11f30 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
11f40 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
11f50 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
11f60 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
11f70 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
11f80 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
11f90 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
11fa0 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
11fb0 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
11fc0 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
11fd0 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
11fe0 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
11ff0 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
12000 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
12010 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
12020 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
12030 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
12040 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
12050 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
12060 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
12070 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
12080 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
12090 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
120a0 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
120b0 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
120c0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
120d0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
120e0 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
120f0 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
12100 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
12110 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
12120 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
12130 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
12140 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
12150 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  able()]..**.** A
12160 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
12170 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
12180 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
12190 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
121a0 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
121b0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
121c0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
121d0 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
121e0 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
121f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
12200 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
12210 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
12220 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
12230 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
12240 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
12250 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
12260 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
12270 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
12280 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
12290 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
122a0 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
122b0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
122c0 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
122d0 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
122e0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
122f0 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
12300 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
12310 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
12320 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
12330 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
12340 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
12350 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
12360 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
12370 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
12380 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
12390 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
123a0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
123b0 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
123c0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
123d0 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
123e0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
123f0 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
12400 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
12410 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
12420 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
12430 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
12440 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
12450 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
12460 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
12470 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
12480 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
12490 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
124a0 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
124b0 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
124c0 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
124d0 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
124e0 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
124f0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
12500 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
12510 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  s 2nd parameter.
12520 20 20 49 74 20 72 65 74 75 72 6e 73 20 61 20 72    It returns a r
12530 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
12540 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
12550 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
12560 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
12570 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e  After the callin
12580 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66  g function has f
12590 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
125a0 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f  e result, it sho
125b0 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65 20  uld.** pass the 
125c0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72  pointer to the r
125d0 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73  esult table to s
125e0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
125f0 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  e() in order to.
12600 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  ** release the m
12610 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d  emory that was m
12620 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73  alloced.  Becaus
12630 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65  e of the way the
12640 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
12650 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77  loc()] happens w
12660 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65  ithin sqlite3_ge
12670 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63  t_table(), the c
12680 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  alling.** functi
12690 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20  on must not try 
126a0 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  to call [sqlite3
126b0 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c  _free()] directl
126c0 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c  y.  Only.** [sql
126d0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
126e0 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65  )] is able to re
126f0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
12700 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61   properly and sa
12710 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fely..**.** The 
12720 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
12730 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
12740 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20   implemented as 
12750 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  a wrapper around
12760 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
12770 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74  c()].  The sqlit
12780 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72  e3_get_table() r
12790 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20  outine does not 
127a0 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  have access.** t
127b0 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64  o any internal d
127c0 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f  ata structures o
127d0 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73  f SQLite.  It us
127e0 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c  es only the publ
127f0 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ic.** interface 
12800 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41  defined here.  A
12810 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c  s a consequence,
12820 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
12830 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61  ur in the.** wra
12840 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69  pper layer outsi
12850 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e  de of the intern
12860 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  al [sqlite3_exec
12870 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74  ()] call are not
12880 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e  .** reflected in
12890 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
128a0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
128b0 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71 6c  rcode()] or [sql
128c0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
128d0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
128e0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 31 7d  :.**.** {H12371}
128f0 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 67   If a [sqlite3_g
12900 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 69 6c  et_table()] fail
12910 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  s a memory alloc
12920 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20  ation, then.**  
12930 20 20 20 20 20 20 20 20 69 74 20 73 68 61 6c 6c          it shall
12940 20 66 72 65 65 20 74 68 65 20 72 65 73 75 6c 74   free the result
12950 20 74 61 62 6c 65 20 75 6e 64 65 72 20 63 6f 6e   table under con
12960 73 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72 74  struction, abort
12970 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
12980 20 71 75 65 72 79 20 69 6e 20 70 72 6f 63 65 73   query in proces
12990 73 2c 20 73 6b 69 70 20 61 6e 79 20 73 75 62 73  s, skip any subs
129a0 65 71 75 65 6e 74 20 71 75 65 72 69 65 73 2c 20  equent queries, 
129b0 73 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  set the.**      
129c0 20 20 20 20 2a 70 61 7a 52 65 73 75 6c 74 20 6f      *pazResult o
129d0 75 74 70 75 74 20 70 6f 69 6e 74 65 72 20 74 6f  utput pointer to
129e0 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75 72 6e   NULL and return
129f0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
12a00 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 33 7d 20  .**.** {H12373} 
12a10 49 66 20 74 68 65 20 70 6e 43 6f 6c 75 6d 6e 20  If the pnColumn 
12a20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
12a30 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
12a40 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a  )] is not NULL.*
12a50 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
12a60 61 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  a successful inv
12a70 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
12a80 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
12a90 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20   shall.**       
12aa0 20 20 20 77 72 69 74 65 20 74 68 65 20 6e 75 6d     write the num
12ab0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
12ac0 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
12ad0 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20    result set of 
12ae0 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a  the query into *
12af0 70 6e 43 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  pnColumn..**.** 
12b00 7b 48 31 32 33 37 34 7d 20 49 66 20 74 68 65 20  {H12374} If the 
12b10 70 6e 52 6f 77 20 70 61 72 61 6d 65 74 65 72 20  pnRow parameter 
12b20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  to [sqlite3_get_
12b30 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20  table()] is not 
12b40 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  NULL.**         
12b50 20 74 68 65 6e 20 61 20 73 75 63 63 65 73 73 66   then a successf
12b60 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
12b70 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
12b80 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20  ble()] shall.** 
12b90 20 20 20 20 20 20 20 20 20 77 72 69 74 65 73 20           writes 
12ba0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
12bb0 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20  ws in the.**    
12bc0 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74        result set
12bd0 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e   of the query in
12be0 74 6f 20 2a 70 6e 52 6f 77 2e 0a 2a 2a 0a 2a 2a  to *pnRow..**.**
12bf0 20 7b 48 31 32 33 37 36 7d 20 41 20 73 75 63 63   {H12376} A succ
12c00 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
12c10 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65  n of [sqlite3_ge
12c20 74 5f 74 61 62 6c 65 28 29 5d 20 74 68 61 74 20  t_table()] that 
12c30 63 6f 6d 70 75 74 65 73 0a 2a 2a 20 20 20 20 20  computes.**     
12c40 20 20 20 20 20 4e 20 72 6f 77 73 20 6f 66 20 72       N rows of r
12c50 65 73 75 6c 74 20 77 69 74 68 20 43 20 63 6f 6c  esult with C col
12c60 75 6d 6e 73 20 70 65 72 20 72 6f 77 20 73 68 61  umns per row sha
12c70 6c 6c 20 6d 61 6b 65 20 2a 70 61 7a 52 65 73 75  ll make *pazResu
12c80 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  lt.**          p
12c90 6f 69 6e 74 20 74 6f 20 61 6e 20 61 72 72 61 79  oint to an array
12ca0 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
12cb0 28 4e 2b 31 29 2a 43 20 73 74 72 69 6e 67 73 20  (N+1)*C strings 
12cc0 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 0a  where the first.
12cd0 2a 2a 20 20 20 20 20 20 20 20 20 20 43 20 73 74  **          C st
12ce0 72 69 6e 67 73 20 61 72 65 20 63 6f 6c 75 6d 6e  rings are column
12cf0 20 6e 61 6d 65 73 20 61 73 20 6f 62 74 61 69 6e   names as obtain
12d00 65 64 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20  ed from.**      
12d10 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
12d20 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20  umn_name()] and 
12d30 74 68 65 20 72 65 73 74 20 61 72 65 20 63 6f 6c  the rest are col
12d40 75 6d 6e 20 72 65 73 75 6c 74 20 76 61 6c 75 65  umn result value
12d50 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62  s.**          ob
12d60 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
12d70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
12d80 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  ()]..**.** {H123
12d90 37 39 7d 20 54 68 65 20 76 61 6c 75 65 73 20 69  79} The values i
12da0 6e 20 74 68 65 20 70 61 7a 52 65 73 75 6c 74 20  n the pazResult 
12db0 61 72 72 61 79 20 72 65 74 75 72 6e 65 64 20 62  array returned b
12dc0 79 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  y [sqlite3_get_t
12dd0 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20  able()].**      
12de0 20 20 20 20 73 68 61 6c 6c 20 72 65 6d 61 69 6e      shall remain
12df0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 63 6c 65   valid until cle
12e00 61 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ared by [sqlite3
12e10 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a  _free_table()]..
12e20 2a 2a 0a 2a 2a 20 7b 48 31 32 33 38 32 7d 20 57  **.** {H12382} W
12e30 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
12e40 75 72 73 20 64 75 72 69 6e 67 20 65 76 61 6c 75  urs during evalu
12e50 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
12e60 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a 2a  3_get_table()].*
12e70 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 66  *          the f
12e80 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65  unction shall se
12e90 74 20 2a 70 61 7a 52 65 73 75 6c 74 20 74 6f 20  t *pazResult to 
12ea0 4e 55 4c 4c 2c 20 77 72 69 74 65 20 61 6e 20 65  NULL, write an e
12eb0 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20  rror message.** 
12ec0 20 20 20 20 20 20 20 20 20 69 6e 74 6f 20 6d 65           into me
12ed0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
12ee0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
12ef0 6f 63 28 29 5d 2c 20 6d 61 6b 65 0a 2a 2a 20 20  oc()], make.**  
12f00 20 20 20 20 20 20 20 20 2a 2a 70 7a 45 72 72 6d          **pzErrm
12f10 73 67 20 70 6f 69 6e 74 20 74 6f 20 74 68 61 74  sg point to that
12f20 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2c 20   error message, 
12f30 61 6e 64 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  and return a.** 
12f40 20 20 20 20 20 20 20 20 20 61 70 70 72 6f 70 72           appropr
12f50 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
12f60 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
12f70 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73  3_get_table(.  s
12f80 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
12f90 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
12fa0 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
12fb0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
12fc0 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
12fd0 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
12fe0 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c  char ***pazResul
12ff0 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73  t,    /* Results
13000 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f   of the query */
13010 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20  .  int *pnRow,  
13020 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
13030 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77  er of result row
13040 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
13050 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d  /.  int *pnColum
13060 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d  n,        /* Num
13070 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  ber of result co
13080 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65  lumns written he
13090 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70  re */.  char **p
130a0 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a  zErrmsg       /*
130b0 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
130c0 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f  en here */.);.vo
130d0 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  id sqlite3_free_
130e0 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
130f0 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
13100 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
13110 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
13120 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34   Functions {H174
13130 30 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 30  00} <S70000><S20
13140 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  000>.**.** These
13150 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
13160 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  rkalikes of the 
13170 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
13180 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
13190 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
131a0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
131b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
131c0 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
131d0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
131e0 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
131f0 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
13200 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
13210 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
13220 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
13230 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
13240 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
13250 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
13260 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
13270 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
13280 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72  free()].  Both r
13290 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
132a0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
132b0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
132c0 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
132d0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
132e0 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
132f0 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
13300 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
13310 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70  * In sqlite3_snp
13320 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
13330 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
13340 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
13350 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
13360 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
13370 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
13380 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
13390 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
133a0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
133b0 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
133c0 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
133d0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
133e0 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
133f0 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
13400 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
13410 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
13420 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
13430 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e  f().  This is an
13440 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
13450 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
13460 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
13470 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
13480 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
13490 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20  tibility.  Note 
134a0 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
134b0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
134c0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
134d0 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
134e0 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
134f0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
13500 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
13510 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
13520 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d   buffer.  We adm
13530 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
13540 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
13550 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
13560 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
13570 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
13580 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
13590 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
135a0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
135b0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
135c0 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
135d0 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
135e0 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73  bility..**.** As
135f0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
13600 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
13610 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
13620 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
13630 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
13640 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
13650 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
13660 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20  erminated.  The 
13670 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
13680 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
13690 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
136a0 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
136b0 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
136c0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
136d0 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
136e0 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
136f0 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
13700 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
13710 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
13720 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ers..**.** These
13730 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
13740 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
13750 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
13760 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
13770 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
13780 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
13790 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
137a0 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
137b0 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
137c0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
137d0 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
137e0 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
137f0 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
13800 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
13810 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f  ..**.** The %q o
13820 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
13830 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
13840 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
13850 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
13860 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
13870 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
13880 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
13890 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
138a0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
138b0 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
138c0 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
138d0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79  ing literal.  By
138e0 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27   doubling each '
138f0 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  \''.** character
13900 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74   it escapes that
13910 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61   character and a
13920 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69  llows it to be i
13930 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20  nserted into.** 
13940 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  the string..**.*
13950 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61  * For example, a
13960 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67  ssume the string
13970 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20   variable zText 
13980 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73  contains text as
13990 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
139a0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
139b0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78  >.**  char *zTex
139c0 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70  t = "It's a happ
139d0 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72  y day!";.** </pr
139e0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
139f0 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73  **.** One can us
13a00 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61  e this text in a
13a10 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
13a20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
13a30 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
13a40 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
13a50 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
13a60 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
13a70 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27  O table VALUES('
13a80 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  %q')", zText);.*
13a90 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
13aa0 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
13ab0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
13ac0 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
13ad0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
13ae0 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  e>.**.** Because
13af0 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73   the %q format s
13b00 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  tring is used, t
13b10 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  he '\'' characte
13b20 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73  r in zText.** is
13b30 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65   escaped and the
13b40 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69   SQL generated i
13b50 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
13b60 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
13b70 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
13b80 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
13b90 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70  UES('It''s a hap
13ba0 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70  py day!').** </p
13bb0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
13bc0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63  .**.** This is c
13bd0 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20  orrect.  Had we 
13be0 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20  used %s instead 
13bf0 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72  of %q, the gener
13c00 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c  ated SQL.** woul
13c10 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69  d have looked li
13c20 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
13c30 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
13c40 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
13c50 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
13c60 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
13c70 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  !');.** </pre></
13c80 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
13c90 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78  * This second ex
13ca0 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20  ample is an SQL 
13cb0 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41  syntax error.  A
13cc0 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65  s a general rule
13cd0 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61   you should.** a
13ce0 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73  lways use %q ins
13cf0 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20  tead of %s when 
13d00 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69  inserting text i
13d10 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74  nto a string lit
13d20 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eral..**.** The 
13d30 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
13d40 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
13d50 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
13d60 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
13d70 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
13d80 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
13d90 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
13da0 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
13db0 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61  eter in the.** a
13dc0 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20  rgument list is 
13dd0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
13de0 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
13df0 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
13e00 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c  without.** singl
13e10 65 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61  e quotes) in pla
13e20 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74  ce of the %Q opt
13e30 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ion.  So, for ex
13e40 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
13e50 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
13e60 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
13e70 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
13e80 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
13e90 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
13ea0 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
13eb0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
13ec0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
13ed0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
13ee0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
13ef0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
13f00 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
13f10 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
13f20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
13f30 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
13f40 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
13f50 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
13f60 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
13f70 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
13f80 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
13f90 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
13fa0 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
13fb0 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25   exactly like "%
13fc0 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  s" with the.** a
13fd0 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
13fe0 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
13ff0 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
14000 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
14010 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
14020 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
14030 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
14040 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d  ut string. {END}
14050 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
14060 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 33  S:.**.** {H17403
14070 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
14080 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b  mprintf()] and [
14090 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
140a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ()] interfaces.*
140b0 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75  *           retu
140c0 72 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74 65  rn either pointe
140d0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
140e0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
140f0 6e 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20  ngs held in.**  
14100 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20           memory 
14110 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
14120 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
14130 20 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   or NULL pointer
14140 73 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  s if.**         
14150 20 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c    a call to [sql
14160 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
14170 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  ails..**.** {H17
14180 34 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  406}  The [sqlit
14190 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
141a0 6e 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20  nterface writes 
141b0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
141c0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 55  d.**           U
141d0 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 74 6f  TF-8 string into
141e0 20 74 68 65 20 62 75 66 66 65 72 20 70 6f 69 6e   the buffer poin
141f0 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 73 65  ted to by the se
14200 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
14210 2a 20 20 20 20 20 20 20 20 20 20 20 70 72 6f 76  *           prov
14220 69 64 65 64 20 74 68 61 74 20 74 68 65 20 66 69  ided that the fi
14230 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
14240 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
14250 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30  ro..**.** {H1740
14260 37 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  7}  The [sqlite3
14270 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74  _snprintf()] int
14280 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
14290 77 72 69 74 65 20 73 6c 6f 74 73 20 6f 66 0a 2a  write slots of.*
142a0 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 73 20  *           its 
142b0 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 28 74  output buffer (t
142c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
142d0 74 65 72 29 20 6f 75 74 73 69 64 65 20 74 68 65  ter) outside the
142e0 20 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20   range.**       
142f0 20 20 20 20 6f 66 20 30 20 74 68 72 6f 75 67 68      of 0 through
14300 20 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 69 73   N-1 (where N is
14310 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
14320 65 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 20 20  eter).**        
14330 20 20 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66     regardless of
14340 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
14350 68 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  he string.**    
14360 20 20 20 20 20 20 20 72 65 71 75 65 73 74 65 64         requested
14370 20 62 79 20 74 68 65 20 66 6f 72 6d 61 74 20 73   by the format s
14380 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2f  pecification..*/
14390 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d  .char *sqlite3_m
143a0 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
143b0 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73  r*,...);.char *s
143c0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
143d0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
143e0 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c  list);.char *sql
143f0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e  ite3_snprintf(in
14400 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
14410 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  ar*, ...);../*.*
14420 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
14430 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
14440 62 73 79 73 74 65 6d 20 7b 48 31 37 33 30 30 7d  bsystem {H17300}
14450 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20000>.**.** 
14460 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
14470 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
14480 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
14490 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
144a0 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
144b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
144c0 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
144d0 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
144e0 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
144f0 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
14500 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
14510 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
14520 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
14530 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
14540 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
14550 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
14560 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
14570 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
14580 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
14590 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
145a0 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
145b0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
145c0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
145d0 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
145e0 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
145f0 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d  .** If sqlite3_m
14600 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
14610 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
14620 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
14630 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
14640 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
14650 2e 20 20 49 66 20 74 68 65 20 70 61 72 61 6d 65  .  If the parame
14660 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
14670 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
14680 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
14690 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
146a0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
146b0 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
146c0 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20  ..**.** Calling 
146d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77  sqlite3_free() w
146e0 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72  ith a pointer pr
146f0 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
14700 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
14710 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
14720 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
14730 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f  leases that memo
14740 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74  ry so.** that it
14750 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64   might be reused
14760 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66  .  The sqlite3_f
14770 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
14780 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
14790 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
147a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
147b0 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
147c0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
147d0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
147e0 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
147f0 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
14800 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
14810 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
14820 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
14830 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
14840 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
14850 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
14860 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
14870 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
14880 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
14890 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
148a0 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
148b0 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
148c0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
148d0 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
148e0 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
148f0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
14900 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
14910 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
14920 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
14930 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
14940 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 66  c() or sqlite3_f
14950 72 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ree()..**.** The
14960 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
14970 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
14980 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20  empts to resize 
14990 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72  a.** prior memor
149a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
149b0 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
149c0 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20  tes, where N is 
149d0 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  the.** second pa
149e0 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65  rameter.  The me
149f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14a00 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73  to be resized is
14a10 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   the first.** pa
14a20 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74 68 65  rameter.  If the
14a30 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
14a40 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
14a50 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
14a60 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
14a70 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
14a80 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
14a90 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
14aa0 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
14ab0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
14ac0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
14ad0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
14ae0 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64  ** If the second
14af0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
14b00 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
14b10 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
14b20 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
14b30 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
14b40 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
14b50 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
14b60 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65  e3_free(P) where
14b70 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20   P is the first 
14b80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
14b90 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
14ba0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ** sqlite3_reall
14bb0 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  oc() returns a p
14bc0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
14bd0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
14be0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
14bf0 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
14c00 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65  NULL if sufficie
14c10 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61  nt memory is una
14c20 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20  vailable..** If 
14c30 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
14c40 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
14c50 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
14c60 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
14c70 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
14c80 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
14c90 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
14ca0 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
14cb0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
14cc0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61  ite3_realloc() a
14cd0 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
14ce0 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
14cf0 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f  ..** If sqlite3_
14d00 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
14d10 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  s NULL, then the
14d20 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
14d30 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65  n.** is not free
14d40 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d  d..**.** The mem
14d50 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
14d60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14d70 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
14d80 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77  lloc().** is alw
14d90 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
14da0 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
14db0 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44  e boundary. {END
14dc0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  }.**.** The defa
14dd0 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ult implementati
14de0 6f 6e 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79  on of the memory
14df0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
14e00 79 73 74 65 6d 20 75 73 65 73 0a 2a 2a 20 74 68  ystem uses.** th
14e10 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c  e malloc(), real
14e20 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
14e30 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
14e40 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
14e50 61 72 79 2e 0a 2a 2a 20 7b 48 31 37 33 38 32 7d  ary..** {H17382}
14e60 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c   However, if SQL
14e70 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
14e80 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
14e90 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c  TE_MEMORY_SIZE=<
14ea0 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72 65 70  i>NNN</i> C prep
14eb0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 28  rocessor macro (
14ec0 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e  where <i>NNN</i>
14ed0 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65  .** is an intege
14ee0 72 29 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  r), then SQLite 
14ef0 63 72 65 61 74 65 20 61 20 73 74 61 74 69 63 20  create a static 
14f00 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65 61 73  array of at leas
14f10 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20  t.** <i>NNN</i> 
14f20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
14f30 64 20 75 73 65 73 20 74 68 61 74 20 61 72 72 61  d uses that arra
14f40 79 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  y for all of its
14f50 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d 6f   dynamic.** memo
14f60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
14f70 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64 69  eds. {END}  Addi
14f80 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  tional memory al
14f90 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73 0a  locator options.
14fa0 2a 2a 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ** may be added 
14fb0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
14fc0 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  es..**.** In SQL
14fd0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
14fe0 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
14ff0 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
15000 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
15010 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
15020 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
15030 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
15040 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
15050 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
15060 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
15070 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
15080 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
15090 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
150a0 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
150b0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
150c0 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
150d0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   used..**.** The
150e0 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
150f0 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
15100 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  s.** the system 
15110 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
15120 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
15130 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
15140 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
15150 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
15160 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
15170 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
15180 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
15190 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
151a0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
151b0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
151c0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
151d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
151e0 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c  rs are detected,
151f0 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65   but.** they are
15200 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
15210 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
15220 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
15230 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
15240 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
15250 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  EM]..**.** INVAR
15260 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
15270 37 33 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69  7303}  The [sqli
15280 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69  te3_malloc(N)] i
15290 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
152a0 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65   either a pointe
152b0 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
152c0 20 20 61 20 6e 65 77 6c 79 20 63 68 65 63 6b 65    a newly checke
152d0 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 6f 66 20 61  d-out block of a
152e0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
152f0 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20  of memory.**    
15300 20 20 20 20 20 20 20 74 68 61 74 20 69 73 20 38         that is 8
15310 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f  -byte aligned, o
15320 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  r it returns NUL
15330 4c 20 69 66 20 69 74 20 69 73 20 75 6e 61 62 6c  L if it is unabl
15340 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  e.**           t
15350 6f 20 66 75 6c 66 69 6c 6c 20 74 68 65 20 72 65  o fulfill the re
15360 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  quest..**.** {H1
15370 37 33 30 34 7d 20 20 54 68 65 20 5b 73 71 6c 69  7304}  The [sqli
15380 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69  te3_malloc(N)] i
15390 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
153a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
153b0 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  if.**           
153c0 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
153d0 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2e  r equal to zero.
153e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 35 7d 20  .**.** {H17305} 
153f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 72   The [sqlite3_fr
15400 65 65 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ee(P)] interface
15410 20 72 65 6c 65 61 73 65 73 20 6d 65 6d 6f 72 79   releases memory
15420 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20   previously.**  
15430 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 65           returne
15440 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
15450 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
15460 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
15470 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d  ,.**           m
15480 61 6b 69 6e 67 20 69 74 20 61 76 61 69 6c 61 62  aking it availab
15490 6c 65 20 66 6f 72 20 72 65 75 73 65 2e 0a 2a 2a  le for reuse..**
154a0 0a 2a 2a 20 7b 48 31 37 33 30 36 7d 20 20 41 20  .** {H17306}  A 
154b0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
154c0 5f 66 72 65 65 28 4e 55 4c 4c 29 5d 20 69 73 20  _free(NULL)] is 
154d0 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
154e0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 30 7d  ..**.** {H17310}
154f0 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c    A call to [sql
15500 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 30 2c 4e  ite3_realloc(0,N
15510 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  )] is equivalent
15520 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20   to a call.**   
15530 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69          to [sqli
15540 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 2e 0a  te3_malloc(N)]..
15550 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 32 7d 20 20  **.** {H17312}  
15560 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
15570 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 30 29 5d  e3_realloc(P,0)]
15580 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
15590 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20  o a call.**     
155a0 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65        to [sqlite
155b0 33 5f 66 72 65 65 28 50 29 5d 2e 0a 2a 2a 0a 2a  3_free(P)]..**.*
155c0 2a 20 7b 48 31 37 33 31 35 7d 20 20 54 68 65 20  * {H17315}  The 
155d0 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
155e0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
155f0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  ()], [sqlite3_re
15600 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20  alloc()],.**    
15610 20 20 20 20 20 20 20 61 6e 64 20 5b 73 71 6c 69         and [sqli
15620 74 65 33 5f 66 72 65 65 28 29 5d 20 66 6f 72 20  te3_free()] for 
15630 61 6c 6c 20 6f 66 20 69 74 73 20 6d 65 6d 6f 72  all of its memor
15640 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 6e 64  y allocation and
15650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 64 65  .**           de
15660 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
15670 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 38 7d  ..**.** {H17318}
15680 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72    The [sqlite3_r
15690 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69 6e 74  ealloc(P,N)] int
156a0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
156b0 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65 72 0a  ither a pointer.
156c0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20  **           to 
156d0 61 20 62 6c 6f 63 6b 20 6f 66 20 63 68 65 63 6b  a block of check
156e0 65 64 2d 6f 75 74 20 6d 65 6d 6f 72 79 20 6f 66  ed-out memory of
156f0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
15700 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20 20 20 20  s in size.**    
15710 20 20 20 20 20 20 20 74 68 61 74 20 69 73 20 38         that is 8
15720 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f  -byte aligned, o
15730 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
15740 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 31 7d  ..**.** {H17321}
15750 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    When [sqlite3_
15760 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65  realloc(P,N)] re
15770 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  turns a non-NULL
15780 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72   pointer, it fir
15790 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  st.**           
157a0 63 6f 70 69 65 73 20 74 68 65 20 66 69 72 73 74  copies the first
157b0 20 4b 20 62 79 74 65 73 20 6f 66 20 63 6f 6e 74   K bytes of cont
157c0 65 6e 74 20 66 72 6f 6d 20 50 20 69 6e 74 6f 20  ent from P into 
157d0 74 68 65 20 6e 65 77 6c 79 0a 2a 2a 20 20 20 20  the newly.**    
157e0 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 64         allocated
157f0 20 62 6c 6f 63 6b 2c 20 77 68 65 72 65 20 4b 20   block, where K 
15800 69 73 20 74 68 65 20 6c 65 73 73 65 72 20 6f 66  is the lesser of
15810 20 4e 20 61 6e 64 20 74 68 65 20 73 69 7a 65 20   N and the size 
15820 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  of.**           
15830 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  the buffer P..**
15840 0a 2a 2a 20 7b 48 31 37 33 32 32 7d 20 20 57 68  .** {H17322}  Wh
15850 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  en [sqlite3_real
15860 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e  loc(P,N)] return
15870 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
15880 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a  nter, it first.*
15890 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 6c 65  *           rele
158a0 61 73 65 73 20 74 68 65 20 62 75 66 66 65 72 20  ases the buffer 
158b0 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 33  P..**.** {H17323
158c0 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  }  When [sqlite3
158d0 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72  _realloc(P,N)] r
158e0 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
158f0 20 62 75 66 66 65 72 20 50 20 69 73 0a 2a 2a 20   buffer P is.** 
15900 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 6d 6f            not mo
15910 64 69 66 69 65 64 20 6f 72 20 72 65 6c 65 61 73  dified or releas
15920 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50  ed..**.** ASSUMP
15930 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
15940 37 33 35 30 7d 20 20 54 68 65 20 70 6f 69 6e 74  7350}  The point
15950 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
15960 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
15970 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
15980 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20 20 20  alloc()].**     
15990 20 20 20 20 20 20 6d 75 73 74 20 62 65 20 65 69        must be ei
159a0 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73  ther NULL or els
159b0 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69  e pointers obtai
159c0 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
159d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 6e  .**           in
159e0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
159f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
15a00 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
15a10 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
15a20 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74  **           not
15a30 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
15a40 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35  ed..**.** {A1735
15a50 31 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  1}  The applicat
15a60 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
15a70 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
15a80 61 72 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  art of.**       
15a90 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d      a block of m
15aa0 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
15ab0 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
15ac0 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
15ad0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 66 72 65      [sqlite3_fre
15ae0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
15af0 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  _realloc()]..*/.
15b00 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
15b10 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
15b20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
15b30 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
15b40 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
15b50 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
15b60 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
15b70 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
15b80 74 69 63 73 20 7b 48 31 37 33 37 30 7d 20 3c 53  tics {H17370} <S
15b90 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c  30210>.**.** SQL
15ba0 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
15bb0 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
15bc0 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
15bd0 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
15be0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
15bf0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
15c00 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
15c10 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
15c20 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
15c30 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
15c40 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
15c50 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
15c60 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  system..**.** IN
15c70 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
15c80 7b 48 31 37 33 37 31 7d 20 54 68 65 20 5b 73 71  {H17371} The [sq
15c90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
15ca0 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  d()] routine ret
15cb0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
15cc0 6f 66 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20  of bytes.**     
15cd0 20 20 20 20 20 6f 66 20 6d 65 6d 6f 72 79 20 63       of memory c
15ce0 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
15cf0 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
15d00 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
15d10 2a 0a 2a 2a 20 7b 48 31 37 33 37 33 7d 20 54 68  *.** {H17373} Th
15d20 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
15d30 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
15d40 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
15d50 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 20 20  he maximum.**   
15d60 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
15d70 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
15d80 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
15d90 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
15da0 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 61  k.**          wa
15db0 73 20 6c 61 73 74 20 72 65 73 65 74 2e 0a 2a 2a  s last reset..**
15dc0 0a 2a 2a 20 7b 48 31 37 33 37 34 7d 20 54 68 65  .** {H17374} The
15dd0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
15de0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
15df0 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
15e00 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
15e10 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
15e20 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
15e30 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
15e40 20 20 20 20 20 20 20 20 20 20 61 64 64 65 64 20            added 
15e50 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
15e60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
15e70 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
15e80 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  oc()],.**       
15e90 20 20 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68     but not overh
15ea0 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
15eb0 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
15ec0 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
15ed0 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69  *          routi
15ee0 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
15ef0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
15f00 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  call..**.** {H17
15f10 33 37 35 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20  375} The memory 
15f20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20  high-water mark 
15f30 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20  is reset to the 
15f40 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
15f50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
15f60 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
15f70 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
15f80 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
15f90 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
15fa0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
15fb0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
15fc0 20 74 72 75 65 2e 20 20 54 68 65 20 76 61 6c 75   true.  The valu
15fd0 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20  e returned.**   
15fe0 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74         by [sqlit
15ff0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
16000 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
16010 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
16020 2a 20 20 20 20 20 20 20 20 20 20 70 72 69 6f 72  *          prior
16030 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a   to the reset..*
16040 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
16050 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
16060 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74  sed(void);.sqlit
16070 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
16080 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
16090 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
160a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
160b0 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
160c0 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
160d0 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32 30 30  r {H17390} <S200
160e0 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  00>.**.** SQLite
160f0 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
16100 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
16110 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
16120 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
16130 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
16140 20 72 61 6e 64 6f 6d 20 52 4f 57 49 44 73 20 77   random ROWIDs w
16150 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
16160 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
16170 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
16180 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
16190 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
161a0 20 52 4f 57 49 44 2e 20 20 54 68 65 20 50 52 4e   ROWID.  The PRN
161b0 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
161c0 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
161d0 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
161e0 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
161f0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
16200 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
16210 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
16220 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
16230 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
16240 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
16250 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74  *.** A call to t
16260 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
16270 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
16280 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
16290 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68  ffer P..**.** Th
162a0 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69  e first time thi
162b0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76  s routine is inv
162c0 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74  oked (either int
162d0 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a  ernally or by.**
162e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
162f0 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65  ) the PRNG is se
16300 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f  eded using rando
16310 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mness obtained.*
16320 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  * from the xRand
16330 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
16340 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
16350 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
16360 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62  t..** On all sub
16370 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
16380 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d  ons, the pseudo-
16390 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
163a0 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
163b0 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
163c0 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
163d0 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
163e0 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
163f0 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ethod..**.** INV
16400 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
16410 48 31 37 33 39 32 7d 20 54 68 65 20 5b 73 71 6c  H17392} The [sql
16420 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
16430 4e 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,P)] interface 
16440 77 72 69 74 65 73 20 4e 20 62 79 74 65 73 20 6f  writes N bytes o
16450 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 69  f.**          hi
16460 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
16470 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  o-randomness int
16480 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a 76  o buffer P..*/.v
16490 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64  oid sqlite3_rand
164a0 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f  omness(int N, vo
164b0 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id *P);../*.** C
164c0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
164d0 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
164e0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48  ion Callbacks {H
164f0 31 32 35 30 30 7d 20 3c 53 37 30 31 30 30 3e 0a  12500} <S70100>.
16500 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
16510 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20 61  ne registers a a
16520 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
16530 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
16540 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
16550 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
16560 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
16570 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
16580 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
16590 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
165a0 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
165b0 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
165c0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
165d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
165e0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
165f0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
16600 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
16610 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
16620 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
16630 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
16640 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a  ].  At various.*
16650 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
16660 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
16670 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
16680 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
16690 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
166a0 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
166b0 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
166c0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
166d0 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
166e0 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
166f0 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68  are allowed.  Th
16700 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16710 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
16720 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
16730 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
16740 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
16750 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
16760 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
16770 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
16780 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
16790 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
167a0 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
167b0 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
167c0 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
167d0 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
167e0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
167f0 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
16800 61 6e 20 65 72 72 6f 72 2e 20 20 49 66 20 74 68  an error.  If th
16810 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16820 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
16830 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
16840 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
16850 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
16860 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
16870 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
16880 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
16890 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
168a0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
168b0 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
168c0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
168d0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
168e0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
168f0 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
16900 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
16910 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
16920 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
16930 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
16940 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65  is ok.  When the
16950 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
16960 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
16970 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
16980 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
16990 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
169a0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
169b0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
169c0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
169d0 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
169e0 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
169f0 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
16a00 64 65 6e 69 65 64 2e 20 20 49 66 20 74 68 65 20  denied.  If the 
16a10 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20  authorizer code 
16a20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
16a30 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
16a40 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
16a50 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
16a60 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
16a70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
16a80 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
16a90 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
16aa0 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
16ab0 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
16ac0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
16ad0 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
16ae0 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
16af0 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
16b00 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
16b10 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
16b20 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
16b30 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
16b40 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
16b50 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
16b60 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
16b70 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
16b80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
16b90 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
16ba0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
16bb0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
16bc0 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
16bd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
16be0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
16bf0 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
16c00 66 61 63 65 2e 20 54 68 65 20 73 65 63 6f 6e 64  face. The second
16c10 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
16c20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
16c30 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
16c40 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
16c50 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
16c60 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
16c70 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
16c80 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
16c90 2e 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f  . The third thro
16ca0 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
16cb0 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
16cc0 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
16cd0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
16ce0 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
16cf0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
16d00 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
16d10 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
16d20 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
16d30 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
16d40 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
16d50 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
16d60 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
16d70 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
16d80 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
16d90 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
16da0 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
16db0 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
16dc0 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
16dd0 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
16de0 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
16df0 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
16e00 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
16e10 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
16e20 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
16e30 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
16e40 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
16e50 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
16e60 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
16e70 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
16e80 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
16e90 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
16ea0 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
16eb0 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
16ec0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
16ed0 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
16ee0 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
16ef0 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
16f00 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
16f10 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
16f20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
16f30 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
16f40 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
16f50 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
16f60 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
16f70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
16f80 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
16f90 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
16fa0 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
16fb0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
16fc0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
16fd0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
16fe0 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
16ff0 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
17000 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
17010 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
17020 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
17030 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
17040 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
17050 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
17060 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
17070 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
17080 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
17090 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
170a0 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
170b0 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
170c0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
170d0 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
170e0 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
170f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17100 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
17110 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
17120 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
17130 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
17140 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
17150 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20 74 68  all.  Disable th
17160 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
17170 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
17180 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
17190 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
171a0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
171b0 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ault..**.** Note
171c0 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
171d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
171e0 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
171f0 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
17200 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
17210 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
17220 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
17230 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
17240 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
17250 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
17260 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
17270 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
17280 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 31  S:.**.** {H12501
17290 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  } The [sqlite3_s
172a0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 44 2c  et_authorizer(D,
172b0 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ...)] interface 
172c0 72 65 67 69 73 74 65 72 73 20 61 0a 2a 2a 20 20  registers a.**  
172d0 20 20 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a          authoriz
172e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
172f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17300 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tion D..**.** {H
17310 31 32 35 30 32 7d 20 54 68 65 20 61 75 74 68 6f  12502} The autho
17320 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
17330 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
17340 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
17350 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 69 6e  **          bein
17360 67 20 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  g compiled..**.*
17370 2a 20 7b 48 31 32 35 30 33 7d 20 49 66 20 74 68  * {H12503} If th
17380 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
17390 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 6e  lback returns an
173a0 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
173b0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  an.**          [
173c0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
173d0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
173e0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
173f0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
17400 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
17410 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
17420 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
17430 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 20 20 20  at caused.**    
17440 20 20 20 20 20 20 74 68 65 20 61 75 74 68 6f 72        the author
17450 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f  izer callback to
17460 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 20   run shall fail 
17470 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20  with an.**      
17480 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f      [SQLITE_ERRO
17490 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  R] error code an
174a0 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  d an appropriate
174b0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
174c0 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 34 7d 20 57  **.** {H12504} W
174d0 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hen the authoriz
174e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
174f0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
17500 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
17510 2a 20 20 20 20 20 20 20 20 20 20 64 65 73 63 72  *          descr
17520 69 62 65 64 20 69 73 20 70 72 6f 63 65 73 73 65  ibed is processe
17530 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a  d normally..**.*
17540 2a 20 7b 48 31 32 35 30 35 7d 20 57 68 65 6e 20  * {H12505} When 
17550 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
17560 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
17570 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
17580 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
17590 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
175a0 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
175b0 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 63 61  ent call that ca
175c0 75 73 65 64 20 74 68 65 0a 2a 2a 20 20 20 20 20  used the.**     
175d0 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20       authorizer 
175e0 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20  callback to run 
175f0 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20 20  shall fail.**   
17600 20 20 20 20 20 20 20 77 69 74 68 20 61 6e 20 5b         with an [
17610 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72  SQLITE_ERROR] er
17620 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20  ror code and an 
17630 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
17640 20 20 20 20 20 20 20 20 20 20 65 78 70 6c 61 69            explai
17650 6e 69 6e 67 20 74 68 61 74 20 61 63 63 65 73 73  ning that access
17660 20 69 73 20 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a   is denied..**.*
17670 2a 20 7b 48 31 32 35 30 36 7d 20 49 66 20 74 68  * {H12506} If th
17680 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64  e authorizer cod
17690 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d  e (the 2nd param
176a0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
176b0 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20  orizer.**       
176c0 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20     callback) is 
176d0 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 6e  [SQLITE_READ] an
176e0 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
176f0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
17700 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  s.**          [S
17710 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 74  QLITE_IGNORE], t
17720 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65 64  hen the prepared
17730 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
17740 6e 73 74 72 75 63 74 65 64 20 74 6f 0a 2a 2a 20  nstructed to.** 
17750 20 20 20 20 20 20 20 20 20 69 6e 73 65 72 74 20           insert 
17760 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
17770 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
17780 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
17790 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 20 20 20  ould have.**    
177a0 20 20 20 20 20 20 62 65 65 6e 20 72 65 61 64 20        been read 
177b0 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
177c0 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
177d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 37 7d  ..**.** {H12507}
177e0 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
177f0 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e 64  er code (the 2nd
17800 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
17810 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20  e authorizer.** 
17820 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
17830 6b 29 20 69 73 20 61 6e 79 74 68 69 6e 67 20 6f  k) is anything o
17840 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
17850 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a  E_READ], then.**
17860 20 20 20 20 20 20 20 20 20 20 61 20 72 65 74 75            a retu
17870 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 47  rn of [SQLITE_IG
17880 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 20 73 61  NORE] has the sa
17890 6d 65 20 65 66 66 65 63 74 20 61 73 20 5b 53 51  me effect as [SQ
178a0 4c 49 54 45 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a 2a  LITE_DENY]..**.*
178b0 2a 20 7b 48 31 32 35 31 30 7d 20 54 68 65 20 66  * {H12510} The f
178c0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
178d0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
178e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
178f0 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  opy of.**       
17900 20 20 20 74 68 65 20 74 68 69 72 64 20 70 61 72     the third par
17910 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
17920 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
17930 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
17940 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31  ce..**.** {H1251
17950 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  1} The second pa
17960 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
17970 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
17980 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  teger.**        
17990 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c    [SQLITE_COPY |
179a0 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
179b0 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
179c0 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
179d0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  on.**          t
179e0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
179f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 32 7d 20  .**.** {H12512} 
17a00 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
17a10 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
17a20 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  rs to the callba
17a30 63 6b 20 61 72 65 0a 2a 2a 20 20 20 20 20 20 20  ck are.**       
17a40 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
17a50 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
17a60 63 6f 6e 74 61 69 6e 0a 2a 2a 20 20 20 20 20 20  contain.**      
17a70 20 20 20 20 61 64 64 69 74 69 6f 6e 61 6c 20 64      additional d
17a80 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
17a90 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
17aa0 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
17ab0 7b 48 31 32 35 32 30 7d 20 45 61 63 68 20 63 61  {H12520} Each ca
17ac0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
17ad0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
17ae0 20 6f 76 65 72 72 69 64 65 73 0a 2a 2a 20 20 20   overrides.**   
17af0 20 20 20 20 20 20 20 61 6e 79 20 70 72 65 76 69         any previ
17b00 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c 65 64 20  ously installed 
17b10 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
17b20 2a 20 7b 48 31 32 35 32 31 7d 20 41 20 4e 55 4c  * {H12521} A NUL
17b30 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d 65 61  L authorizer mea
17b40 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74 68 6f  ns that no autho
17b50 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  rization.**     
17b60 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 69 73       callback is
17b70 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
17b80 7b 48 31 32 35 32 32 7d 20 54 68 65 20 64 65 66  {H12522} The def
17b90 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 72 20  ault authorizer 
17ba0 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  is NULL..*/.int 
17bb0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
17bc0 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
17bd0 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
17be0 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
17bf0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
17c00 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
17c10 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
17c20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
17c30 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
17c40 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
17c50 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b 48 31  Return Codes {H1
17c60 32 35 39 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a  2590} <H12500>.*
17c70 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
17c80 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
17c90 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
17ca0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
17cb0 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
17cc0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
17cd0 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
17ce0 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
17cf0 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
17d00 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
17d10 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
17d20 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
17d30 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
17d40 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
17d50 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
17d60 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
17d70 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
17d80 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
17d90 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ion..*/.#define 
17da0 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20  SQLITE_DENY   1 
17db0 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53    /* Abort the S
17dc0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  QL statement wit
17dd0 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64  h an error */.#d
17de0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e  efine SQLITE_IGN
17df0 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74  ORE 2   /* Don't
17e00 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62   allow access, b
17e10 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74  ut don't generat
17e20 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f  e an error */../
17e30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
17e40 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e  uthorizer Action
17e50 20 43 6f 64 65 73 20 7b 48 31 32 35 35 30 7d 20   Codes {H12550} 
17e60 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12500>.**.** T
17e70 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
17e80 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
17e90 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
17ea0 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
17eb0 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  ction.** that is
17ec0 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68   invoked to auth
17ed0 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51  orize certain SQ
17ee0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69  L statement acti
17ef0 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ons.  The.** sec
17f00 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
17f10 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
17f20 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
17f30 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
17f40 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
17f50 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
17f60 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
17f70 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
17f80 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
17f90 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
17fa0 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
17fb0 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  assed..**.** The
17fc0 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76  se action code v
17fd0 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68  alues signify wh
17fe0 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61  at kind of opera
17ff0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a  tion is to be.**
18000 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
18010 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
18020 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
18030 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
18040 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
18050 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d  on will be param
18060 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
18070 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
18080 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64   of these.** cod
18090 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68  es is used as th
180a0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
180b0 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 61 72  er.  The 5th par
180c0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
180d0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
180e0 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
180f0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
18100 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
18110 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70  ,.** etc.) if ap
18120 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 20 36  plicable.  The 6
18130 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
18140 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
18150 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
18160 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
18170 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
18180 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
18190 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
181a0 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
181b0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
181c0 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
181d0 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
181e0 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
181f0 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a  vel SQL code..**
18200 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
18210 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 31 7d 20 54  **.** {H12551} T
18220 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18230 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 20 20 20  ter to an.**    
18240 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
18250 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
18260 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18270 61 63 6b 5d 20 69 73 20 61 6c 77 61 79 73 20 61  ack] is always a
18280 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20  n integer.**    
18290 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f        [SQLITE_CO
182a0 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  PY | authorizer 
182b0 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
182c0 66 69 65 73 20 77 68 61 74 20 61 63 74 69 6f 6e  fies what action
182d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
182e0 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
182f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 32 7d  ..**.** {H12552}
18300 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
18310 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
18320 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
18330 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
18340 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
18350 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 5d  zation callback]
18360 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c  .**          wil
18370 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
18380 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
18390 67 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 20 20  g on which.**   
183a0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43         [SQLITE_C
183b0 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  OPY | authorizer
183c0 20 63 6f 64 65 5d 20 69 73 20 75 73 65 64 20 61   code] is used a
183d0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
183e0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ameter..**.** {H
183f0 31 32 35 35 33 7d 20 54 68 65 20 35 74 68 20 70  12553} The 5th p
18400 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
18410 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
18420 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
18430 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
18440 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74 68   callback] is th
18450 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e name.**       
18460 20 20 20 6f 66 20 74 68 65 20 64 61 74 61 62 61     of the databa
18470 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d 61  se (example: "ma
18480 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65 74 63  in", "temp", etc
18490 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
184a0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 34 7d  ..**.** {H12554}
184b0 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74   The 6th paramet
184c0 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  er to the.**    
184d0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
184e0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
184f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18500 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d 65  ack] is the name
18510 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
18520 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
18530 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
18540 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
18550 6c 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  le for.**       
18560 20 20 20 74 68 65 20 61 63 63 65 73 73 20 61 74     the access at
18570 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
18580 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
18590 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
185a0 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20   from.**        
185b0 20 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20    top-level SQL 
185c0 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
185d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
185e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
185f0 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
18600 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
18610 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
18620 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
18630 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
18640 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
18650 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
18660 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18670 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
18680 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
18690 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
186a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
186b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
186c0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
186d0 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
186e0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
186f0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
18700 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18710 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
18720 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
18730 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18740 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18750 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18760 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
18770 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
18780 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
18790 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
187a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
187b0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
187c0 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
187d0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
187e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
187f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18800 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
18810 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
18820 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
18830 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
18840 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18850 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
18860 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
18870 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
18880 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
188a0 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
188b0 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
188c0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
188d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
188e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
188f0 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
18900 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
18910 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
18920 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
18930 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
18940 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
18950 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
18960 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
18970 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
18980 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
18990 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
189a0 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
189b0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
189c0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
189d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
189e0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
189f0 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
18a00 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
18a10 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18a20 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
18a30 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
18a40 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
18a50 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
18a60 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
18a70 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
18a80 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
18a90 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
18aa0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18ab0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18ac0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
18ad0 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
18ae0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
18af0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
18b00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18b10 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
18b20 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
18b30 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
18b40 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18b50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18b60 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
18b70 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
18b80 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
18b90 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
18ba0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18bb0 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
18bc0 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
18bd0 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
18be0 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
18bf0 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
18c00 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
18c10 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
18c20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18c30 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
18c40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18c50 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
18c60 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
18c70 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
18c80 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
18c90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18ca0 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
18cb0 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4e         22   /* N
18cc0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
18cd0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18ce0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18cf0 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
18d00 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
18d10 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
18d20 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
18d30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18d40 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
18d50 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
18d60 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
18d70 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18d80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18d90 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
18da0 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
18db0 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
18dc0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
18dd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
18de0 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
18df0 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
18e00 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
18e10 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
18e20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
18e30 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
18e40 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
18e50 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
18e60 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
18e70 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
18e80 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
18e90 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
18ea0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
18eb0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18ec0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
18ed0 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
18ee0 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
18ef0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
18f00 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
18f10 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
18f20 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
18f30 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
18f40 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
18f50 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
18f60 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
18f70 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
18f80 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e     /* Function N
18f90 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
18fa0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18fb0 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
18fc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
18fd0 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
18fe0 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
18ff0 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
19000 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
19010 6e 63 74 69 6f 6e 73 20 7b 48 31 32 32 38 30 7d  nctions {H12280}
19020 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 20 45 58 50   <S60400>.** EXP
19030 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
19040 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
19050 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
19060 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
19070 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
19080 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
19090 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
190a0 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
190b0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
190c0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
190d0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
190e0 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
190f0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
19100 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
19110 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
19120 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
19130 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
19140 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68  3_step()]..** Th
19150 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
19160 6e 73 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  ns a UTF-8 rende
19170 72 69 6e 67 20 6f 66 20 74 68 65 20 53 51 4c 20  ring of the SQL 
19180 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a  statement text.*
19190 2a 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  * as the stateme
191a0 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
191b0 65 78 65 63 75 74 69 6e 67 2e 20 20 41 64 64 69  executing.  Addi
191c0 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  tional callbacks
191d0 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63   occur.** as eac
191e0 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70  h triggered subp
191f0 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65  rogram is entere
19200 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  d.  The callback
19210 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a  s for triggers.*
19220 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d  * contain a UTF-
19230 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68  8 SQL comment th
19240 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68  at identifies th
19250 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a  e trigger..**.**
19260 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
19270 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
19280 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
19290 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
192a0 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
192b0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
192c0 68 65 73 2e 20 20 54 68 65 20 70 72 6f 66 69 6c  hes.  The profil
192d0 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
192e0 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  ins.** the origi
192f0 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  nal statement te
19300 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61  xt and an estima
19310 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  te of wall-clock
19320 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20   time.** of how 
19330 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
19340 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
19350 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
19360 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 31  S:.**.** {H12281
19370 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  } The callback f
19380 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
19390 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 74  ed by [sqlite3_t
193a0 72 61 63 65 28 29 5d 20 69 73 0a 2a 2a 20 20 20  race()] is.**   
193b0 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72 20         whenever 
193c0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
193d0 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f   first begins to
193e0 20 65 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a 20   execute and.** 
193f0 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 65           wheneve
19400 72 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70  r a trigger subp
19410 72 6f 67 72 61 6d 20 66 69 72 73 74 20 62 65 67  rogram first beg
19420 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a  ins to run..**.*
19430 2a 20 7b 48 31 32 32 38 32 7d 20 45 61 63 68 20  * {H12282} Each 
19440 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
19450 5f 74 72 61 63 65 28 29 5d 20 6f 76 65 72 72 69  _trace()] overri
19460 64 65 73 20 74 68 65 20 70 72 65 76 69 6f 75 73  des the previous
19470 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ly.**          r
19480 65 67 69 73 74 65 72 65 64 20 74 72 61 63 65 20  egistered trace 
19490 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
194a0 7b 48 31 32 32 38 33 7d 20 41 20 4e 55 4c 4c 20  {H12283} A NULL 
194b0 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 64  trace callback d
194c0 69 73 61 62 6c 65 73 20 74 72 61 63 69 6e 67 2e  isables tracing.
194d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 34 7d 20  .**.** {H12284} 
194e0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
194f0 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20  nt to the trace 
19500 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
19510 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  py of.**        
19520 20 20 74 68 65 20 70 6f 69 6e 74 65 72 20 77 68    the pointer wh
19530 69 63 68 20 77 61 73 20 74 68 65 20 33 72 64 20  ich was the 3rd 
19540 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
19550 69 74 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a 2a  ite3_trace()]..*
19560 2a 0a 2a 2a 20 7b 48 31 32 32 38 35 7d 20 54 68  *.** {H12285} Th
19570 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
19580 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63  t to the trace c
19590 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20  allback is a.** 
195a0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
195b0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
195c0 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
195d0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 74 65   the original te
195e0 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  xt.**          o
195f0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
19600 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70 61  ent as it was pa
19610 73 73 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69 74  ssed into [sqlit
19620 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
19630 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
19640 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2c 20  the equivalent, 
19650 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e  or an SQL commen
19660 74 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65  t indicating the
19670 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20   beginning.**   
19680 20 20 20 20 20 20 20 6f 66 20 61 20 74 72 69 67         of a trig
19690 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 0a  ger subprogram..
196a0 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 37 7d 20 54  **.** {H12287} T
196b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
196c0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
196d0 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66  by [sqlite3_prof
196e0 69 6c 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ile()] is invoke
196f0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  d.**          as
19700 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
19710 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a  ent finishes..**
19720 0a 2a 2a 20 7b 48 31 32 32 38 38 7d 20 54 68 65  .** {H12288} The
19730 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
19740 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20   to the profile 
19750 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
19760 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  py of.**        
19770 20 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65    the 3rd parame
19780 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
19790 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  profile()]..**.*
197a0 2a 20 7b 48 31 32 32 38 39 7d 20 54 68 65 20 73  * {H12289} The s
197b0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
197c0 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63  to the profile c
197d0 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20  allback is a.** 
197e0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
197f0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
19800 74 72 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61  tring that conta
19810 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65 74 65  ins the complete
19820 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20 20   text of.**     
19830 20 20 20 20 20 74 68 65 20 53 51 4c 20 73 74 61       the SQL sta
19840 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73  tement as it was
19850 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 5b 73   processed by [s
19860 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
19870 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  2()].**         
19880 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
19890 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 39  nt..**.** {H1229
198a0 30 7d 20 54 68 65 20 74 68 69 72 64 20 70 61 72  0} The third par
198b0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72  ameter to the pr
198c0 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69  ofile callback i
198d0 73 20 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a 2a  s an estimate.**
198e0 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
198f0 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73   number of nanos
19900 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d 63  econds of wall-c
19910 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71 75 69 72  lock time requir
19920 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ed to.**        
19930 20 20 72 75 6e 20 74 68 65 20 53 51 4c 20 73 74    run the SQL st
19940 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74 61  atement from sta
19950 72 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f  rt to finish..*/
19960 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74  .void *sqlite3_t
19970 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76  race(sqlite3*, v
19980 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
19990 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
199a0 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73   void*);.void *s
199b0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
199c0 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
199d0 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
199e0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
199f0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
19a00 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
19a10 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
19a20 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
19a30 20 7b 48 31 32 39 31 30 7d 20 3c 53 36 30 34 30   {H12910} <S6040
19a40 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
19a50 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73  utine configures
19a60 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
19a70 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72  tion - the.** pr
19a80 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
19a90 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  - that is invoke
19aa0 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
19ab0 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75  uring long.** ru
19ac0 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b  nning calls to [
19ad0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
19ae0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19af0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
19b00 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20  3_get_table()]. 
19b10 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
19b20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
19b30 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
19b40 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
19b50 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
19b60 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ery..**.** If th
19b70 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
19b80 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
19b90 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
19ba0 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
19bb0 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
19bc0 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
19bd0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
19be0 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
19bf0 6f 6e 20 6f 6e 20 61 20 47 55 49 20 64 69 61 6c  on on a GUI dial
19c00 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49 4e  og box..**.** IN
19c10 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
19c20 7b 48 31 32 39 31 31 7d 20 54 68 65 20 63 61 6c  {H12911} The cal
19c30 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
19c40 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
19c50 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
19c60 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 20  ndler().**      
19c70 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 70      is invoked p
19c80 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
19c90 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
19ca0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20  calls to.**     
19cb0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74       [sqlite3_st
19cc0 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ep()]..**.** {H1
19cd0 32 39 31 32 7d 20 54 68 65 20 70 72 6f 67 72 65  2912} The progre
19ce0 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  ss callback is i
19cf0 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20  nvoked once for 
19d00 65 76 65 72 79 20 4e 20 76 69 72 74 75 61 6c 0a  every N virtual.
19d10 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 61 63 68  **          mach
19d20 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77 68 65  ine opcodes, whe
19d30 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
19d40 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
19d50 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
19d60 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
19d70 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63 61 6c 6c  _handler()] call
19d80 20 74 68 61 74 20 72 65 67 69 73 74 65 72 65 64   that registered
19d90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
19da0 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 4e   callback.  If N
19db0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31 2c   is less than 1,
19dc0 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
19dd0 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20  s_handler().**  
19de0 20 20 20 20 20 20 20 20 61 63 74 73 20 61 73 20          acts as 
19df0 69 66 20 61 20 4e 55 4c 4c 20 70 72 6f 67 72 65  if a NULL progre
19e00 73 73 20 68 61 6e 64 6c 65 72 20 68 61 64 20 62  ss handler had b
19e10 65 65 6e 20 73 70 65 63 69 66 69 65 64 2e 0a 2a  een specified..*
19e20 2a 0a 2a 2a 20 7b 48 31 32 39 31 33 7d 20 54 68  *.** {H12913} Th
19e30 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
19e40 61 63 6b 20 69 74 73 65 6c 66 20 69 73 20 69 64  ack itself is id
19e50 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
19e60 74 68 69 72 64 0a 2a 2a 20 20 20 20 20 20 20 20  third.**        
19e70 20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71    argument to sq
19e80 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
19e90 61 6e 64 6c 65 72 28 29 2e 0a 2a 2a 0a 2a 2a 20  andler()..**.** 
19ea0 7b 48 31 32 39 31 34 7d 20 54 68 65 20 66 6f 75  {H12914} The fou
19eb0 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
19ec0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
19ed0 5f 68 61 6e 64 6c 65 72 28 29 20 69 73 20 61 0a  _handler() is a.
19ee0 2a 2a 20 20 20 20 20 20 20 20 20 20 76 6f 69 64  **          void
19ef0 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
19f00 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  to the progress 
19f10 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
19f20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 65 61       function ea
19f30 63 68 20 74 69 6d 65 20 69 74 20 69 73 20 69 6e  ch time it is in
19f40 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  voked..**.** {H1
19f50 32 39 31 35 7d 20 49 66 20 61 20 63 61 6c 6c 20  2915} If a call 
19f60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
19f70 28 29 5d 20 72 65 73 75 6c 74 73 20 69 6e 20 66  ()] results in f
19f80 65 77 65 72 20 74 68 61 6e 20 4e 20 6f 70 63 6f  ewer than N opco
19f90 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  des.**          
19fa0 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 2c 20  being executed, 
19fb0 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73  then the progres
19fc0 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65  s callback is ne
19fd0 76 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a  ver invoked..**.
19fe0 2a 2a 20 7b 48 31 32 39 31 36 7d 20 45 76 65 72  ** {H12916} Ever
19ff0 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  y call to [sqlit
1a000 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1a010 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ler()].**       
1a020 20 20 20 6f 76 65 72 77 72 69 74 65 73 20 61 6e     overwrites an
1a030 79 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  y previously reg
1a040 69 73 74 65 72 65 64 20 70 72 6f 67 72 65 73 73  istered progress
1a050 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
1a060 7b 48 31 32 39 31 37 7d 20 49 66 20 74 68 65 20  {H12917} If the 
1a070 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1a080 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
1a090 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65  L then no progre
1a0a0 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  ss.**          h
1a0b0 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65  andler is invoke
1a0c0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 38  d..**.** {H12918
1a0d0 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73  } If the progres
1a0e0 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
1a0f0 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68 65  ns a result othe
1a100 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a  r than 0, then.*
1a110 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62  *          the b
1a120 65 68 61 76 69 6f 72 20 69 73 20 61 20 69 66 20  ehavior is a if 
1a130 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
1a140 70 74 28 29 5d 20 68 61 64 20 62 65 65 6e 20 63  pt()] had been c
1a150 61 6c 6c 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20  alled..**       
1a160 20 20 20 3c 53 33 30 35 30 30 3e 0a 2a 2f 0a 76     <S30500>.*/.v
1a170 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  oid sqlite3_prog
1a180 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c  ress_handler(sql
1a190 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28  ite3*, int, int(
1a1a0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
1a1b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a1c0 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65  EF: Opening A Ne
1a1d0 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  w Database Conne
1a1e0 63 74 69 6f 6e 20 7b 48 31 32 37 30 30 7d 20 3c  ction {H12700} <
1a1f0 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S40200>.**.** Th
1a200 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
1a210 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
1a220 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20  base file whose 
1a230 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79  name is given by
1a240 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
1a250 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 66   argument. The f
1a260 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1a270 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1a280 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
1a290 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1a2a0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1a2b0 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
1a2c0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1a2d0 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
1a2e0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
1a2f0 36 28 29 2e 20 41 20 5b 64 61 74 61 62 61 73 65  6(). A [database
1a300 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1a310 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
1a320 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
1a330 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
1a340 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
1a350 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
1a360 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
1a370 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
1a380 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
1a390 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1a3a0 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1a3b0 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
1a3c0 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
1a3d0 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
1a3e0 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
1a3f0 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
1a400 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65 20 64  object. If the d
1a410 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1a420 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
1a430 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
1a440 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
1a450 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
1a460 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
1a470 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
1a480 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a  returned.  The.*
1a490 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1a4a0 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
1a4b0 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
1a4c0 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
1a4d0 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
1a4e0 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
1a4f0 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
1a500 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a  f the error..**.
1a510 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 65  ** The default e
1a520 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20  ncoding for the 
1a530 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1a540 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c   UTF-8 if.** sql
1a550 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1a560 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1a570 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a   is called and.*
1a580 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  * UTF-16 in the 
1a590 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1a5a0 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  r if sqlite3_ope
1a5b0 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a  n16() is used..*
1a5c0 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
1a5d0 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
1a5e0 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
1a5f0 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
1a600 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1a610 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
1a620 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
1a630 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
1a640 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
1a650 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
1a660 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
1a670 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
1a680 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
1a690 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
1a6a0 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
1a6b0 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
1a6c0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
1a6d0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
1a6e0 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
1a6f0 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
1a700 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
1a710 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
1a720 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
1a730 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
1a740 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
1a750 72 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  r can take one o
1a760 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
1a770 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
1a780 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
1a790 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
1a7a0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
1a7b0 4f 4d 55 54 45 58 5d 20 66 6c 61 67 3a 0a 2a 2a  OMUTEX] flag:.**
1a7c0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
1a7d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1a7e0 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
1a7f0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1a800 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
1a810 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
1a820 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
1a830 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
1a840 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
1a850 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
1a860 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53  dd>.**.** <dt>[S
1a870 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1a880 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
1a890 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1a8a0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1a8b0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
1a8c0 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
1a8d0 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
1a8e0 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
1a8f0 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
1a900 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
1a910 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
1a920 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
1a930 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
1a940 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
1a950 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
1a960 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
1a970 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c  >.**.** <dt>[SQL
1a980 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1a990 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
1a9a0 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
1a9b0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
1a9c0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
1a9d0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
1a9e0 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
1a9f0 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69  eates it if.** i
1aa00 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
1aa10 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
1aa20 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
1aa30 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
1aa40 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
1aa50 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1aa60 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
1aa70 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  dd>.** </dl>.**.
1aa80 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
1aa90 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1aaa0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1aab0 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
1aac0 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
1aad0 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e  hown above or on
1aae0 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61  e of the combina
1aaf0 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
1ab00 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69  e combined.** wi
1ab10 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
1ab20 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
1ab30 67 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  g, then the beha
1ab40 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
1ab50 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
1ab60 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1ab70 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1ab80 74 2c 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  t, then mutexes 
1ab90 6f 6e 20 74 68 65 0a 2a 2a 20 6f 70 65 6e 65 64  on the.** opened
1aba0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1abb0 63 74 69 6f 6e 5d 20 61 72 65 20 64 69 73 61 62  ction] are disab
1abc0 6c 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c  led and the appl
1abd0 69 61 74 69 6f 6e 20 6d 75 73 74 0a 2a 2a 20 69  iation must.** i
1abe0 6e 73 75 72 65 20 74 68 61 74 20 61 63 63 65 73  nsure that acces
1abf0 73 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  s to the [databa
1ac00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
1ac10 6e 64 20 69 74 73 20 61 73 73 6f 63 69 61 74 65  nd its associate
1ac20 64 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  d.** [prepared s
1ac30 74 61 74 65 6d 65 6e 74 73 5d 20 69 73 20 73 65  tatements] is se
1ac40 72 69 61 6c 69 7a 65 64 2e 20 20 54 68 65 20 5b  rialized.  The [
1ac50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1ac60 54 45 58 5d 20 66 6c 61 67 0a 2a 2a 20 69 73 20  TEX] flag.** is 
1ac70 74 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  the default beha
1ac80 76 69 6f 72 20 69 73 20 53 51 4c 69 74 65 20 69  vior is SQLite i
1ac90 73 20 63 6f 6e 66 69 67 75 72 65 64 20 75 73 69  s configured usi
1aca0 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ng the.** [SQLIT
1acb0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
1acc0 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
1acd0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
1ace0 52 45 41 44 5d 20 6f 70 74 69 6f 6e 73 0a 2a 2a  READ] options.**
1acf0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
1ad00 66 69 67 28 29 5d 2e 20 20 54 68 65 20 5b 53 51  fig()].  The [SQ
1ad10 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1ad20 58 5d 20 66 6c 61 67 20 6f 6e 6c 79 20 6d 61 6b  X] flag only mak
1ad30 65 73 20 61 0a 2a 2a 20 64 69 66 66 65 72 65 6e  es a.** differen
1ad40 63 65 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ce when SQLite i
1ad50 73 20 69 6e 20 69 74 73 20 64 65 66 61 75 6c 74  s in its default
1ad60 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
1ad70 53 45 52 49 41 4c 49 5a 45 44 5d 20 6d 6f 64 65  SERIALIZED] mode
1ad80 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  ..**.** If the f
1ad90 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
1ada0 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
1adb0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
1adc0 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1add0 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
1ade0 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
1adf0 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d  tion.  This in-m
1ae00 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
1ae10 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
1ae20 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1ae30 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
1ae40 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
1ae50 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1ae60 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
1ae70 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
1ae80 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
1ae90 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
1aea0 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
1aeb0 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
1aec0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
1aed0 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
1aee0 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
1aef0 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
1af00 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
1af10 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
1af20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
1af30 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
1af40 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
1af50 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
1af60 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66  iguity..**.** If
1af70 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1af80 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
1af90 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
1afa0 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
1afb0 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
1afc0 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
1afd0 20 20 54 68 69 73 20 70 72 69 76 61 74 65 20 64    This private d
1afe0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
1aff0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
1b000 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
1b010 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
1b020 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
1b030 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
1b040 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1b050 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
1b060 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
1b070 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
1b080 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1b090 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
1b0a0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
1b0b0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
1b0c0 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
1b0d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b0e0 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49  n should use.  I
1b0f0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
1b100 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
1b110 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1b120 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1b130 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1b140 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
1b150 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
1b160 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
1b170 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
1b180 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
1b190 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
1b1a0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
1b1b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1b1c0 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55  n_v2() must be U
1b1d0 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
1b1e0 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
1b1f0 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
1b200 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
1b210 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
1b220 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
1b230 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
1b240 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
1b250 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
1b260 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
1b270 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
1b280 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
1b290 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  2()..**.** INVAR
1b2a0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
1b2b0 32 37 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2701} The [sqlit
1b2c0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
1b2d0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
1b2e0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
1b2f0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1b300 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 63  ()] interfaces c
1b310 72 65 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20  reate a new.**  
1b320 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
1b330 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73  e connection] as
1b340 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
1b350 20 20 20 20 20 20 20 20 20 20 74 68 65 20 64 61            the da
1b360 74 61 62 61 73 65 20 66 69 6c 65 20 67 69 76 65  tabase file give
1b370 6e 20 69 6e 20 74 68 65 69 72 20 66 69 72 73 74  n in their first
1b380 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1b390 2a 20 7b 48 31 32 37 30 32 7d 20 54 68 65 20 66  * {H12702} The f
1b3a0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1b3b0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1b3c0 61 73 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20  as UTF-8.**     
1b3d0 20 20 20 20 20 66 6f 72 20 5b 73 71 6c 69 74 65       for [sqlite
1b3e0 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73  3_open()] and [s
1b3f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1b400 5d 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 0a  ] and as UTF-16.
1b410 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 74  **          in t
1b420 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
1b430 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65  rder for [sqlite
1b440 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a  3_open16()]..**.
1b450 2a 2a 20 7b 48 31 32 37 30 33 7d 20 41 20 73 75  ** {H12703} A su
1b460 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
1b470 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1b480 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
1b490 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20  3_open16()],.** 
1b4a0 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
1b4b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
1b4c0 77 72 69 74 65 73 20 61 20 70 6f 69 6e 74 65 72  writes a pointer
1b4d0 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20   to a new.**    
1b4e0 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
1b4f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 6f  connection] into
1b500 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 48   *ppDb..**.** {H
1b510 31 32 37 30 34 7d 20 54 68 65 20 5b 73 71 6c 69  12704} The [sqli
1b520 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1b530 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
1b540 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
1b550 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1b560 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
1b570 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1b580 4b 5d 20 75 70 6f 6e 20 73 75 63 63 65 73 73 2c  K] upon success,
1b590 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
1b5a0 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
1b5b0 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66  error code] on f
1b5c0 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ailure..**.** {H
1b5d0 31 32 37 30 36 7d 20 54 68 65 20 64 65 66 61 75  12706} The defau
1b5e0 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  lt text encoding
1b5f0 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62   for a new datab
1b600 61 73 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  ase created usin
1b610 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
1b620 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f  qlite3_open()] o
1b630 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
1b640 76 32 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54  v2()] will be UT
1b650 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  F-8..**.** {H127
1b660 30 37 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20  07} The default 
1b670 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  text encoding fo
1b680 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65  r a new database
1b690 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
1b6a0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1b6b0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 77 69  te3_open16()] wi
1b6c0 6c 6c 20 62 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  ll be UTF-16..**
1b6d0 0a 2a 2a 20 7b 48 31 32 37 30 39 7d 20 54 68 65  .** {H12709} The
1b6e0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 46   [sqlite3_open(F
1b6f0 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69  ,D)] interface i
1b700 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a  s equivalent to.
1b710 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1b720 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
1b730 2c 47 2c 30 29 5d 20 77 68 65 72 65 20 74 68 65  ,G,0)] where the
1b740 20 47 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a   G parameter is.
1b750 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
1b760 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1b770 54 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  TE]|[SQLITE_OPEN
1b780 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20  _CREATE]..**.** 
1b790 7b 48 31 32 37 31 31 7d 20 49 66 20 74 68 65 20  {H12711} If the 
1b7a0 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  G parameter to [
1b7b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1b7c0 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69  F,D,G,V)] contai
1b7d0 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
1b7e0 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51     bit value [SQ
1b7f0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
1b800 4c 59 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74  LY] then the dat
1b810 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a  abase is opened.
1b820 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  **          for 
1b830 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a  reading only..**
1b840 0a 2a 2a 20 7b 48 31 32 37 31 32 7d 20 49 66 20  .** {H12712} If 
1b850 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20  the G parameter 
1b860 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
1b870 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f  _v2(F,D,G,V)] co
1b880 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20  ntains the.**   
1b890 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65         bit value
1b8a0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
1b8b0 41 44 57 52 49 54 45 5d 20 74 68 65 6e 20 74 68  ADWRITE] then th
1b8c0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1b8d0 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ened.**         
1b8e0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1b8f0 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
1b900 2c 20 6f 72 20 66 6f 72 20 72 65 61 64 69 6e 67  , or for reading
1b910 20 6f 6e 6c 79 20 69 66 20 74 68 65 0a 2a 2a 20   only if the.** 
1b920 20 20 20 20 20 20 20 20 20 66 69 6c 65 20 69 73           file is
1b930 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
1b940 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
1b950 67 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  g system..**.** 
1b960 7b 48 31 32 37 31 33 7d 20 49 66 20 74 68 65 20  {H12713} If the 
1b970 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  G parameter to [
1b980 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32 28  sqlite3_open(v2(
1b990 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 20  F,D,G,V)] omits 
1b9a0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1b9b0 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  bit value [SQLIT
1b9c0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61  E_OPEN_CREATE] a
1b9d0 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  nd the database 
1b9e0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20  does not.**     
1b9f0 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20       previously 
1ba00 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
1ba10 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1ba20 2a 2a 20 7b 48 31 32 37 31 34 7d 20 49 66 20 74  ** {H12714} If t
1ba30 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74  he G parameter t
1ba40 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
1ba50 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e  v2(F,D,G,V)] con
1ba60 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  tains the.**    
1ba70 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20        bit value 
1ba80 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
1ba90 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74  ATE] and the dat
1baa0 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
1bab0 2a 20 20 20 20 20 20 20 20 20 20 70 72 65 76 69  *          previ
1bac0 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 74 68 65  ously exist, the
1bad0 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  n an attempt is 
1bae0 6d 61 64 65 20 74 6f 20 63 72 65 61 74 65 20 61  made to create a
1baf0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  nd.**          i
1bb00 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 64 61  nitialize the da
1bb10 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tabase..**.** {H
1bb20 31 32 37 31 37 7d 20 49 66 20 74 68 65 20 66 69  12717} If the fi
1bb30 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
1bb40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
1bb50 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1bb60 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  en16()],.**     
1bb70 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
1bb80 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 22  _open_v2()] is "
1bb90 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
1bba0 61 6e 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20  an private,.**  
1bbb0 20 20 20 20 20 20 20 20 65 70 68 65 6d 65 72 61          ephemera
1bbc0 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  l, in-memory dat
1bbd0 61 62 61 73 65 20 69 73 20 63 72 65 61 74 65 64  abase is created
1bbe0 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
1bbf0 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ion..**         
1bc00 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45   <todo>Is SQLITE
1bc10 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c  _OPEN_CREATE|SQL
1bc20 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1bc30 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20  TE required.**  
1bc40 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74          in sqlit
1bc50 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74  e3_open_v2()?</t
1bc60 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  odo>.**.** {H127
1bc70 31 39 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e  19} If the filen
1bc80 61 6d 65 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61  ame is NULL or a
1bc90 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
1bca0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 0a  then a private,.
1bcb0 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70 68 65  **          ephe
1bcc0 6d 65 72 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61  meral on-disk da
1bcd0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
1bce0 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20  reated..**      
1bcf0 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c      <todo>Is SQL
1bd00 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c  ITE_OPEN_CREATE|
1bd10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1bd20 57 52 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a  WRITE required.*
1bd30 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 73 71  *          in sq
1bd40 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f  lite3_open_v2()?
1bd50 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48  </todo>.**.** {H
1bd60 31 32 37 32 31 7d 20 54 68 65 20 5b 64 61 74 61  12721} The [data
1bd70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1bd80 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c   created by [sql
1bd90 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
1bda0 2c 47 2c 56 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,G,V)].**       
1bdb0 20 20 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20     will use the 
1bdc0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1bdd0 6a 65 63 74 20 69 64 65 6e 74 69 66 69 65 64 20  ject identified 
1bde0 62 79 20 74 68 65 20 56 20 70 61 72 61 6d 65 74  by the V paramet
1bdf0 65 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  er,.**          
1be00 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  or the default [
1be10 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1be20 65 63 74 20 69 66 20 56 20 69 73 20 61 20 4e 55  ect if V is a NU
1be30 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1be40 2a 20 7b 48 31 32 37 32 33 7d 20 54 77 6f 20 5b  * {H12723} Two [
1be50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1be60 69 6f 6e 73 5d 20 77 69 6c 6c 20 73 68 61 72 65  ions] will share
1be70 20 61 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 20   a common cache 
1be80 69 66 20 62 6f 74 68 20 77 65 72 65 0a 2a 2a 20  if both were.** 
1be90 20 20 20 20 20 20 20 20 20 6f 70 65 6e 65 64 20           opened 
1bea0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 56 46  with the same VF
1beb0 53 20 77 68 69 6c 65 20 5b 73 68 61 72 65 64 20  S while [shared 
1bec0 63 61 63 68 65 20 6d 6f 64 65 5d 20 77 61 73 20  cache mode] was 
1bed0 65 6e 61 62 6c 65 64 20 61 6e 64 0a 2a 2a 20 20  enabled and.**  
1bee0 20 20 20 20 20 20 20 20 69 66 20 62 6f 74 68 20          if both 
1bef0 66 69 6c 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72  filenames compar
1bf00 65 20 65 71 75 61 6c 20 75 73 69 6e 67 20 6d 65  e equal using me
1bf10 6d 63 6d 70 28 29 20 61 66 74 65 72 20 68 61 76  mcmp() after hav
1bf20 69 6e 67 20 62 65 65 6e 0a 2a 2a 20 20 20 20 20  ing been.**     
1bf30 20 20 20 20 20 70 72 6f 63 65 73 73 65 64 20 62       processed b
1bf40 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
1bf50 66 73 20 7c 20 78 46 75 6c 6c 50 61 74 68 6e 61  fs | xFullPathna
1bf60 6d 65 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  me] method of th
1bf70 65 20 56 46 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71  e VFS..*/.int sq
1bf80 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
1bf90 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
1bfa0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
1bfb0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
1bfc0 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
1bfd0 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
1bfe0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1bff0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
1c000 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
1c010 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
1c020 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
1c030 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
1c040 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
1c050 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
1c060 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1c070 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1c080 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1c090 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
1c0a0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
1c0b0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
1c0c0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
1c0d0 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
1c0e0 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
1c0f0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1c100 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
1c110 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
1c120 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
1c130 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1c140 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
1c150 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
1c160 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
1c170 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c180 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20  Error Codes And 
1c190 4d 65 73 73 61 67 65 73 20 7b 48 31 32 38 30 30  Messages {H12800
1c1a0 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60200>.**.**
1c1b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72   The sqlite3_err
1c1c0 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65  code() interface
1c1d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1c1e0 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
1c1f0 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
1c200 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
1c210 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
1c220 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74  ent failed sqlit
1c230 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a  e3_* API call.**
1c240 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1c250 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
1c260 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70  nection]. If a p
1c270 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61  rior API call fa
1c280 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20  iled.** but the 
1c290 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
1c2a0 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20  call succeeded, 
1c2b0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1c2c0 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
1c2d0 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e  _errcode() is un
1c2e0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
1c2f0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
1c300 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
1c310 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
1c320 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
1c330 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
1c340 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
1c350 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
1c360 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
1c370 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
1c380 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
1c390 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
1c3a0 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
1c3b0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
1c3c0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1c3d0 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
1c3e0 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
1c3f0 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
1c400 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
1c410 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
1c420 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
1c430 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
1c440 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
1c450 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
1c460 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
1c470 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  face functions..
1c480 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
1c490 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
1c4a0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
1c4b0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
1c4c0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
1c4d0 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
1c4e0 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
1c4f0 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
1c500 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
1c510 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
1c520 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
1c530 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  not be set..**.*
1c540 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1c550 0a 2a 2a 20 7b 48 31 32 38 30 31 7d 20 54 68 65  .** {H12801} The
1c560 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1c570 65 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(D)] interface 
1c580 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
1c590 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ric.**          
1c5a0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
1c5b0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
1c5c0 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
1c5d0 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a 2a 2a  most recently.**
1c5e0 20 20 20 20 20 20 20 20 20 20 66 61 69 6c 65 64            failed
1c5f0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20   interface call 
1c600 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1c610 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
1c620 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
1c630 2a 2a 20 7b 48 31 32 38 30 33 7d 20 54 68 65 20  ** {H12803} The 
1c640 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1c650 44 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  D)] and [sqlite3
1c660 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 0a 2a 2a  _errmsg16(D)].**
1c670 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
1c680 61 63 65 73 20 72 65 74 75 72 6e 20 45 6e 67 6c  aces return Engl
1c690 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78  ish-language tex
1c6a0 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
1c6b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1c6c0 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 6d 6f   error in the mo
1c6d0 73 74 6c 79 20 72 65 63 65 6e 74 6c 79 20 66 61  stly recently fa
1c6e0 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63  iled interface c
1c6f0 61 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  all,.**         
1c700 20 65 6e 63 6f 64 65 64 20 61 73 20 65 69 74 68   encoded as eith
1c710 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1c720 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
1c730 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 37 7d 20  .**.** {H12807} 
1c740 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
1c750 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1c760 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b  _errmsg()] and [
1c770 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1c780 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
1c790 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
1c7a0 74 68 65 20 6e 65 78 74 20 53 51 4c 69 74 65 20  the next SQLite 
1c7b0 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a  interface call..
1c7c0 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 38 7d 20 43  **.** {H12808} C
1c7d0 61 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f 75 74  alls to API rout
1c7e0 69 6e 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  ines that do not
1c7f0 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72   return an error
1c800 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
1c810 20 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c    (example: [sql
1c820 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
1c830 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20  )]) do not.**   
1c840 20 20 20 20 20 20 20 63 68 61 6e 67 65 20 74 68         change th
1c850 65 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 72 20  e error code or 
1c860 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e 65 64  message returned
1c870 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
1c880 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
1c890 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72  ()], [sqlite3_er
1c8a0 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c  rmsg()], or [sql
1c8b0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
1c8c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 39 7d  ..**.** {H12809}
1c8d0 20 49 6e 74 65 72 66 61 63 65 73 20 74 68 61 74   Interfaces that
1c8e0 20 61 72 65 20 6e 6f 74 20 61 73 73 6f 63 69 61   are not associa
1c8f0 74 65 64 20 77 69 74 68 20 61 20 73 70 65 63 69  ted with a speci
1c900 66 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  fic.**          
1c910 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1c920 74 69 6f 6e 5d 20 28 65 78 61 6d 70 6c 65 73 3a  tion] (examples:
1c930 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1c940 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
1c950 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61   or [sqlite3_ena
1c960 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
1c970 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
1c980 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  do not change th
1c990 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
1c9a0 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
1c9b0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1c9c0 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65  e()], [sqlite3_e
1c9d0 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71  rrmsg()], or [sq
1c9e0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1c9f0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
1ca00 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
1ca10 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68  3 *db);.const ch
1ca20 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
1ca30 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  sg(sqlite3*);.co
1ca40 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
1ca50 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
1ca60 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1ca70 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65  I3REF: SQL State
1ca80 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33  ment Object {H13
1ca90 30 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 2a  000} <H13010>.**
1caa0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
1cab0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
1cac0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
1cad0 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
1cae0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
1caf0 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
1cb00 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  s a single SQL s
1cb10 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69  tatement..** Thi
1cb20 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69  s object is vari
1cb30 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61  ously known as a
1cb40 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65   "prepared state
1cb50 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63  ment" or a.** "c
1cb60 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
1cb70 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79  ement" or simply
1cb80 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74   as a "statement
1cb90 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66  "..**.** The lif
1cba0 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74  e of a statement
1cbb0 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d   object goes som
1cbc0 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73  ething like this
1cbd0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
1cbe0 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20  <li> Create the 
1cbf0 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
1cc00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1cc10 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64  ()] or a related
1cc20 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f  .**      functio
1cc30 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20  n..** <li> Bind 
1cc40 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20  values to [host 
1cc50 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e  parameters] usin
1cc60 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
1cc70 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69  nd_*().**      i
1cc80 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c  nterfaces..** <l
1cc90 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
1cca0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
1ccb0 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
1ccc0 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
1ccd0 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
1cce0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
1ccf0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1cd00 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
1cd10 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
1cd20 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
1cd30 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
1cd40 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
1cd50 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
1cd60 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1cd70 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
1cd80 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f  *.** Refer to do
1cd90 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69  cumentation on i
1cda0 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64  ndividual method
1cdb0 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69  s above for addi
1cdc0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
1cdd0 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ation..*/.typede
1cde0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
1cdf0 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
1ce00 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
1ce10 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
1ce20 6d 69 74 73 20 7b 48 31 32 37 36 30 7d 20 3c 53  mits {H12760} <S
1ce30 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  20600>.**.** Thi
1ce40 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
1ce50 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76  ws the size of v
1ce60 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74  arious construct
1ce70 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a  s to be limited.
1ce80 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69  ** on a connecti
1ce90 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e  on by connection
1cea0 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72   basis.  The fir
1ceb0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
1cec0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
1ced0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f   connection] who
1cee0 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62  se limit is to b
1cef0 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64  e set or queried
1cf00 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
1cf10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
1cf20 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20  e of the [limit 
1cf30 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74  categories] that
1cf40 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61   define a.** cla
1cf50 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73  ss of constructs
1cf60 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69   to be size limi
1cf70 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20  ted.  The third 
1cf80 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
1cf90 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f  .** new limit fo
1cfa0 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74  r that construct
1cfb0 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20  .  The function 
1cfc0 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20  returns the old 
1cfd0 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  limit..**.** If 
1cfe0 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
1cff0 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
1d000 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
1d010 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46   unchanged..** F
1d020 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74  or the limit cat
1d030 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f  egory of SQLITE_
1d040 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20  LIMIT_XYZ there 
1d050 69 73 20 61 20 68 61 72 64 20 75 70 70 65 72 0a  is a hard upper.
1d060 2a 2a 20 62 6f 75 6e 64 20 73 65 74 20 62 79 20  ** bound set by 
1d070 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43  a compile-time C
1d080 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1d090 63 72 6f 20 6e 61 6d 65 64 20 53 51 4c 49 54 45  cro named SQLITE
1d0a0 5f 4d 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54 68  _MAX_XYZ..** (Th
1d0b0 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
1d0c0 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
1d0d0 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a  ed to "_MAX_".).
1d0e0 2a 2a 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69  ** Attempts to i
1d0f0 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
1d100 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
1d110 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
1d120 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
1d130 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
1d140 20 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a   upper limit..**
1d150 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d  .** Run time lim
1d160 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  its are intended
1d170 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c   for use in appl
1d180 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61  ications that ma
1d190 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65  nage.** both the
1d1a0 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20  ir own internal 
1d1b0 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73  database and als
1d1c0 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74  o databases that
1d1d0 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a   are controlled.
1d1e0 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20  ** by untrusted 
1d1f0 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
1d200 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70  .  An example ap
1d210 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
1d220 62 65 20 61 0a 2a 2a 20 77 65 62 62 72 6f 77 73  be a.** webbrows
1d230 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20  er that has its 
1d240 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f  own databases fo
1d250 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72  r storing histor
1d260 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74  y and.** separat
1d270 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74  e databases cont
1d280 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63  rolled by JavaSc
1d290 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ript application
1d2a0 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20  s downloaded.** 
1d2b0 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74  off the Internet
1d2c0 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20  .  The internal 
1d2d0 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65  databases can be
1d2e0 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61   given the.** la
1d2f0 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d  rge, default lim
1d300 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20  its.  Databases 
1d310 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72  managed by exter
1d320 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a  nal sources can.
1d330 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68  ** be given much
1d340 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20   smaller limits 
1d350 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76  designed to prev
1d360 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20  ent a denial of 
1d370 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63  service.** attac
1d380 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d  k.  Developers m
1d390 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74  ight also want t
1d3a0 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74  o use the [sqlit
1d3b0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1d3c0 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  r()].** interfac
1d3d0 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e  e to further con
1d3e0 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53  trol untrusted S
1d3f0 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  QL.  The size of
1d400 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
1d410 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75   created by an u
1d420 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20  ntrusted script 
1d430 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  can be contained
1d440 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d   using the.** [m
1d450 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
1d460 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e  PRAGMA]..**.** N
1d470 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ew run-time limi
1d480 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79  t categories may
1d490 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
1d4a0 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  ure releases..**
1d4b0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1d4c0 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 32 7d 20 41  **.** {H12762} A
1d4d0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
1d4e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   to [sqlite3_lim
1d4f0 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65  it(D,C,V)] where
1d500 20 56 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20   V is.**        
1d510 20 20 70 6f 73 69 74 69 76 65 20 63 68 61 6e 67    positive chang
1d520 65 73 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20  es the limit on 
1d530 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73  the size of cons
1d540 74 72 75 63 74 20 43 20 69 6e 20 74 68 65 0a 2a  truct C in the.*
1d550 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
1d560 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1d570 20 44 20 74 6f 20 74 68 65 20 6c 65 73 73 65 72   D to the lesser
1d580 20 6f 66 20 56 20 61 6e 64 20 74 68 65 20 68 61   of V and the ha
1d590 72 64 20 75 70 70 65 72 0a 2a 2a 20 20 20 20 20  rd upper.**     
1d5a0 20 20 20 20 20 62 6f 75 6e 64 20 6f 6e 20 74 68       bound on th
1d5b0 65 20 73 69 7a 65 20 6f 66 20 43 20 74 68 61 74  e size of C that
1d5c0 20 69 73 20 73 65 74 20 61 74 20 63 6f 6d 70 69   is set at compi
1d5d0 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b  le-time..**.** {
1d5e0 48 31 32 37 36 36 7d 20 41 20 73 75 63 63 65 73  H12766} A succes
1d5f0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
1d600 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c  lite3_limit(D,C,
1d610 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 20 6e  V)] where V is n
1d620 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20  egative.**      
1d630 20 20 20 20 6c 65 61 76 65 73 20 74 68 65 20 73      leaves the s
1d640 74 61 74 65 20 6f 66 20 74 68 65 20 5b 64 61 74  tate of the [dat
1d650 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d660 5d 20 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ] D unchanged..*
1d670 2a 0a 2a 2a 20 7b 48 31 32 37 36 39 7d 20 41 20  *.** {H12769} A 
1d680 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
1d690 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  to [sqlite3_limi
1d6a0 74 28 44 2c 43 2c 56 29 5d 20 72 65 74 75 72 6e  t(D,C,V)] return
1d6b0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
1d6c0 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c    value of the l
1d6d0 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65  imit on the size
1d6e0 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20   of construct C 
1d6f0 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
1d700 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
1d710 6e 65 63 74 69 6f 6e 5d 20 44 20 61 73 20 69 74  nection] D as it
1d720 20 77 61 73 20 70 72 69 6f 72 20 74 6f 20 74 68   was prior to th
1d730 65 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  e call..*/.int s
1d740 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
1d750 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
1d760 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
1d770 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1d780 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
1d790 67 6f 72 69 65 73 20 7b 48 31 32 37 39 30 7d 20  gories {H12790} 
1d7a0 3c 48 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 57  <H12760>.** KEYW
1d7b0 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
1d7c0 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61  egory} {limit ca
1d7d0 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
1d7e0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
1d7f0 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 61  define various a
1d800 73 70 65 63 74 73 20 6f 66 20 61 20 5b 64 61 74  spects of a [dat
1d810 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d820 5d 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  ].** that can be
1d830 20 6c 69 6d 69 74 65 64 20 69 6e 20 73 69 7a 65   limited in size
1d840 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   by calls to [sq
1d850 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a  lite3_limit()]..
1d860 2a 2a 20 54 68 65 20 6d 65 61 6e 69 6e 67 73 20  ** The meanings 
1d870 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  of the various l
1d880 69 6d 69 74 73 20 61 72 65 20 61 73 20 66 6f 6c  imits are as fol
1d890 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  lows:.**.** <dl>
1d8a0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1d8b0 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  IMIT_LENGTH</dt>
1d8c0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1d8d0 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20  mum size of any 
1d8e0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f  string or BLOB o
1d8f0 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e  r table row.<dd>
1d900 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1d910 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
1d920 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1d930 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
1d940 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
1d950 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ement.</dd>.**.*
1d960 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1d970 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
1d980 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1d990 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
1d9a0 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
1d9b0 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
1d9c0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
1d9d0 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 6f 72  t of a SELECT or
1d9e0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
1d9f0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1da00 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
1da10 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
1da20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
1da30 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  se.</dd>.**.** <
1da40 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1da50 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
1da60 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1da70 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
1da80 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
1da90 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
1daa0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1dab0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
1dac0 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
1dad0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1dae0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
1daf0 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
1db00 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
1db10 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1db20 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  >SQLITE_LIMIT_VD
1db30 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BE_OP</dt>.** <d
1db40 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1db50 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74  mber of instruct
1db60 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61  ions in a virtua
1db70 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61  l machine progra
1db80 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70  m.** used to imp
1db90 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74  lement an SQL st
1dba0 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a  atement.</dd>.**
1dbb0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1dbc0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
1dbd0 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
1dbe0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1dbf0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
1dc00 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
1dc10 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1dc20 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
1dc30 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
1dc40 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1dc50 20 6f 66 20 61 74 74 61 63 68 65 64 20 64 61 74   of attached dat
1dc60 61 62 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  abases.</dd>.**.
1dc70 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1dc80 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
1dc90 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1dca0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1dcb0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
1dcc0 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
1dcd0 6f 20 74 68 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a  o the LIKE or.**
1dce0 20 47 4c 4f 42 20 6f 70 65 72 61 74 6f 72 73 2e   GLOB operators.
1dcf0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1dd00 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
1dd10 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
1dd20 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1dd30 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76  imum number of v
1dd40 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53  ariables in an S
1dd50 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
1dd60 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e  t can.** be boun
1dd70 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e  d.</dd>.** </dl>
1dd80 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1dd90 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
1dda0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1ddb0 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
1ddc0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
1ddd0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
1dde0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
1ddf0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
1de00 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
1de10 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
1de20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
1de30 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
1de40 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
1de50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
1de60 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
1de70 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
1de80 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
1de90 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
1dea0 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
1deb0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
1dec0 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
1ded0 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
1dee0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1def0 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
1df00 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
1df10 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1df20 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
1df30 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
1df40 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1df50 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1df60 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f  R           9../
1df70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1df80 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
1df90 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 31  Statement {H1301
1dfa0 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b  0} <S10000>.** K
1dfb0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
1dfc0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
1dfd0 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
1dfe0 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
1dff0 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
1e000 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
1e010 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
1e020 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
1e030 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1e040 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
1e050 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
1e060 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
1e070 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
1e080 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
1e090 2a 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  * prior call to 
1e0a0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1e0b0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
1e0c0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
1e0d0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a  3_open16()]..**.
1e0e0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
1e0f0 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
1e100 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
1e110 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
1e120 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
1e130 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
1e140 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
1e150 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
1e160 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
1e170 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
1e180 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
1e190 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1e1a0 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
1e1b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1e1c0 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
1e1d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e  ..**.** If the n
1e1e0 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
1e1f0 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
1e200 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
1e210 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
1e220 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
1e230 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 20  nator. If nByte 
1e240 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
1e250 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20   then it is the 
1e260 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65  maximum.** numbe
1e270 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64  r of  bytes read
1e280 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65   from zSql.  Whe
1e290 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  n nByte is non-n
1e2a0 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20  egative, the.** 
1e2b0 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73  zSql string ends
1e2c0 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66   at either the f
1e2d0 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27  irst '\000' or '
1e2e0 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65  \u0000' characte
1e2f0 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74  r or.** the nByt
1e300 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68  e-th byte, which
1e310 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
1e320 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20  . If the caller 
1e330 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68  knows.** that th
1e340 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
1e350 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
1e360 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20  ted, then there 
1e370 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65  is a small.** pe
1e380 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
1e390 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64  age to be gained
1e3a0 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e   by passing an n
1e3b0 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74  Byte parameter t
1e3c0 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20  hat.** is equal 
1e3d0 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  to the number of
1e3e0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e   bytes in the in
1e3f0 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e  put string <i>in
1e400 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74  cluding</i>.** t
1e410 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f  he nul-terminato
1e420 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a  r bytes..**.** *
1e430 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
1e440 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
1e450 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20 74  irst byte past t
1e460 68 65 20 65 6e 64 20 6f 66 20 74 68 65 0a 2a 2a  he end of the.**
1e470 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
1e480 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
1e490 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
1e4a0 6c 79 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66  ly compile the f
1e4b0 69 72 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  irst.** statemen
1e4c0 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
1e4d0 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
1e4e0 69 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72  inting to what r
1e4f0 65 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70  emains.** uncomp
1e500 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53  iled..**.** *ppS
1e510 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
1e520 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
1e530 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
1e540 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
1e550 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
1e560 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
1e570 74 65 70 28 29 5d 2e 20 20 49 66 20 74 68 65 72  tep()].  If ther
1e580 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
1e590 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a  ppStmt is set.**
1e5a0 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68   to NULL.  If th
1e5b0 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  e input text con
1e5c0 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66  tains no SQL (if
1e5d0 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e   the input is an
1e5e0 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67   empty.** string
1e5f0 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74   or a comment) t
1e600 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73  hen *ppStmt is s
1e610 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b  et to NULL..** {
1e620 41 31 33 30 31 38 7d 20 54 68 65 20 63 61 6c 6c  A13018} The call
1e630 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
1e640 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
1e650 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
1e660 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74  mpiled.** SQL st
1e670 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
1e680 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1e690 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
1e6a0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
1e6b0 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65  ..**.** On succe
1e6c0 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  ss, [SQLITE_OK] 
1e6d0 69 73 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 68  is returned, oth
1e6e0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
1e6f0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
1e700 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1e710 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e720 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
1e730 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
1e740 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
1e750 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
1e760 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
1e770 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
1e780 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
1e790 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
1e7a0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1e7b0 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
1e7c0 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
1e7d0 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20  aged..** In the 
1e7e0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c  "v2" interfaces,
1e7f0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
1e800 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20  atement.** that 
1e810 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65  is returned (the
1e820 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
1e830 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73  object) contains
1e840 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
1e850 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
1e860 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73  ext. This causes
1e870 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
1e880 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ep()] interface 
1e890 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64  to.** behave a d
1e8a0 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77  ifferently in tw
1e8b0 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  o ways:.**.** <o
1e8c0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66  l>.** <li>.** If
1e8d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
1e8e0 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
1e8f0 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
1e900 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
1e910 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
1e920 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
1e930 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1e940 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
1e950 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
1e960 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
1e970 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
1e980 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74   it again.  If t
1e990 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68  he schema has ch
1e9a0 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61  anged in.** a wa
1e9b0 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  y that makes the
1e9c0 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f   statement no lo
1e9d0 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c  nger valid, [sql
1e9e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
1e9f0 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  l still.** retur
1ea00 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
1ea10 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74  ].  But unlike t
1ea20 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
1ea30 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  or, [SQLITE_SCHE
1ea40 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20  MA] is.** now a 
1ea50 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61  fatal error.  Ca
1ea60 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  lling [sqlite3_p
1ea70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61  repare_v2()] aga
1ea80 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65  in will not make
1ea90 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f   the.** error go
1eaa0 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73   away.  Note: us
1eab0 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  e [sqlite3_errms
1eac0 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65  g()] to find the
1ead0 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20   text.** of the 
1eae0 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68  parsing error th
1eaf0 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e  at results in an
1eb00 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1eb10 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69   return..** </li
1eb20 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
1eb30 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
1eb40 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73  curs, [sqlite3_s
1eb50 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
1eb60 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
1eb70 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72  tailed.** [error
1eb80 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
1eb90 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
1eba0 5d 2e 20 20 54 68 65 20 6c 65 67 61 63 79 20 62  ].  The legacy b
1ebb0 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
1ebc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
1ebd0 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
1ebe0 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
1ebf0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
1ec00 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
1ec10 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76  nd you would hav
1ec20 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
1ec30 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
1ec40 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20  te3_reset()] in 
1ec50 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64  order.** to find
1ec60 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
1ec70 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
1ec80 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
1ec90 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
1eca0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
1ecb0 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
1ecc0 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
1ecd0 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
1ece0 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
1ecf0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
1ed00 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1ed10 2a 20 7b 48 31 33 30 31 31 7d 20 54 68 65 20 5b  * {H13011} The [
1ed20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1ed30 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e  db,zSql,...)] an
1ed40 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
1ed50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1ed60 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20  2(db,zSql,...)] 
1ed70 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65 72  interfaces inter
1ed80 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  pret the.**     
1ed90 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 68 65       text in the
1eda0 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65  ir zSql paramete
1edb0 72 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  r as UTF-8..**.*
1edc0 2a 20 7b 48 31 33 30 31 32 7d 20 54 68 65 20 5b  * {H13012} The [
1edd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1ede0 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20  6(db,zSql,...)] 
1edf0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
1ee00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1ee10 31 36 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e  16_v2(db,zSql,..
1ee20 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69  .)] interfaces i
1ee30 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20  nterpret the.** 
1ee40 20 20 20 20 20 20 20 20 20 74 65 78 74 20 69 6e           text in
1ee50 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61   their zSql para
1ee60 6d 65 74 65 72 20 61 73 20 55 54 46 2d 31 36 20  meter as UTF-16 
1ee70 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1ee80 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20  te order..**.** 
1ee90 7b 48 31 33 30 31 33 7d 20 49 66 20 74 68 65 20  {H13013} If the 
1eea0 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74  nByte argument t
1eeb0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
1eec0 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42  re_v2(db,zSql,nB
1eed0 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  yte,...)].**    
1eee0 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 61        and its va
1eef0 72 69 61 6e 74 73 20 69 73 20 6c 65 73 73 20 74  riants is less t
1ef00 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 20 53 51  han zero, the SQ
1ef10 4c 20 74 65 78 74 20 69 73 0a 2a 2a 20 20 20 20  L text is.**    
1ef20 20 20 20 20 20 20 72 65 61 64 20 66 72 6f 6d 20        read from 
1ef30 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
1ef40 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
1ef50 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
1ef60 0a 2a 2a 20 7b 48 31 33 30 31 34 7d 20 49 66 20  .** {H13014} If 
1ef70 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
1ef80 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  nt to [sqlite3_p
1ef90 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71  repare_v2(db,zSq
1efa0 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a  l,nByte,...)].**
1efb0 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 69 74            and it
1efc0 73 20 76 61 72 69 61 6e 74 73 20 69 73 20 6e 6f  s variants is no
1efd0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
1efe0 20 61 74 20 6d 6f 73 74 20 6e 42 79 74 65 73 20   at most nBytes 
1eff0 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20  bytes of.**     
1f000 20 20 20 20 20 53 51 4c 20 74 65 78 74 20 69 73       SQL text is
1f010 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
1f020 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 35 7d 20  .**.** {H13015} 
1f030 49 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  In [sqlite3_prep
1f040 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e  are_v2(db,zSql,N
1f050 2c 50 2c 70 7a 54 61 69 6c 29 5d 20 61 6e 64 20  ,P,pzTail)] and 
1f060 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20  its variants.** 
1f070 20 20 20 20 20 20 20 20 20 69 66 20 74 68 65 20           if the 
1f080 7a 53 71 6c 20 69 6e 70 75 74 20 74 65 78 74 20  zSql input text 
1f090 63 6f 6e 74 61 69 6e 73 20 6d 6f 72 65 20 74 68  contains more th
1f0a0 61 6e 20 6f 6e 65 20 53 51 4c 20 73 74 61 74 65  an one SQL state
1f0b0 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ment.**         
1f0c0 20 61 6e 64 20 70 7a 54 61 69 6c 20 69 73 20 6e   and pzTail is n
1f0d0 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a 70  ot NULL, then *p
1f0e0 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
1f0f0 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 0a 2a 2a   point to the.**
1f100 20 20 20 20 20 20 20 20 20 20 66 69 72 73 74 20            first 
1f110 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65 6e  byte past the en
1f120 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
1f130 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1f140 7a 53 71 6c 2e 0a 2a 2a 20 20 20 20 20 20 20 20  zSql..**        
1f150 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 64 6f 65    <todo>What doe
1f160 73 20 2a 70 7a 54 61 69 6c 20 70 6f 69 6e 74 20  s *pzTail point 
1f170 74 6f 20 69 66 20 74 68 65 72 65 20 69 73 20 6f  to if there is o
1f180 6e 65 20 73 74 61 74 65 6d 65 6e 74 3f 3c 2f 74  ne statement?</t
1f190 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30  odo>.**.** {H130
1f1a0 31 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  16} A successful
1f1b0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1f1c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c  3_prepare_v2(db,
1f1d0 7a 53 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e  zSql,N,ppStmt,..
1f1e0 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
1f1f0 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
1f200 72 69 61 6e 74 73 20 77 72 69 74 65 73 20 69 6e  riants writes in
1f210 74 6f 20 2a 70 70 53 74 6d 74 20 61 20 70 6f 69  to *ppStmt a poi
1f220 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a  nter to a new.**
1f230 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
1f240 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
1f250 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e  r a pointer to N
1f260 55 4c 4c 20 69 66 20 7a 53 71 6c 20 63 6f 6e 74  ULL if zSql cont
1f270 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ains.**         
1f280 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74   nothing other t
1f290 68 61 6e 20 77 68 69 74 65 73 70 61 63 65 20 6f  han whitespace o
1f2a0 72 20 63 6f 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  r comments..**.*
1f2b0 2a 20 7b 48 31 33 30 31 39 7d 20 54 68 65 20 5b  * {H13019} The [
1f2c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1f2d0 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
1f2e0 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
1f2f0 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20   return.**      
1f300 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20      [SQLITE_OK] 
1f310 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
1f320 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  e [error code] u
1f330 70 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a  pon failure..**.
1f340 2a 2a 20 7b 48 31 33 30 32 31 7d 20 42 65 66 6f  ** {H13021} Befo
1f350 72 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  re [sqlite3_prep
1f360 61 72 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74  are(db,zSql,nByt
1f370 65 2c 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c 29  e,ppStmt,pzTail)
1f380 5d 20 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20 20  ] or its.**     
1f390 20 20 20 20 20 76 61 72 69 61 6e 74 73 20 72 65       variants re
1f3a0 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 20 28  turns an error (
1f3b0 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
1f3c0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
1f3d0 29 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ),.**          t
1f3e0 68 65 79 20 66 69 72 73 74 20 73 65 74 20 2a 70  hey first set *p
1f3f0 70 53 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  pStmt to NULL..*
1f400 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  /.int sqlite3_pr
1f410 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
1f420 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1f430 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1f440 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1f450 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
1f460 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1f470 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
1f480 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1f490 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1f4a0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1f4b0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1f4c0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1f4d0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1f4e0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1f4f0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1f500 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
1f510 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1f520 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1f530 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1f540 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1f550 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
1f560 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1f570 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1f580 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1f590 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1f5a0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1f5b0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
1f5c0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1f5d0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1f5e0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1f5f0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1f600 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1f610 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1f620 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1f630 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1f640 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
1f650 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1f660 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1f670 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1f680 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
1f690 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1f6a0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1f6b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1f6c0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1f6d0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1f6e0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1f6f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1f700 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
1f710 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1f720 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1f730 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1f740 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1f750 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1f760 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1f770 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1f780 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1f790 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
1f7a0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1f7b0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1f7c0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1f7d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1f7e0 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c  pare16_v2(.  sql
1f7f0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1f800 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
1f810 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1f820 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
1f830 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
1f840 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
1f850 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1f860 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1f870 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1f880 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1f890 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1f8a0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1f8b0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1f8c0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1f8d0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
1f8e0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1f8f0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1f900 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1f910 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  Sql */.);../*.**
1f920 20 43 41 50 49 52 45 46 3a 20 52 65 74 72 69 65   CAPIREF: Retrie
1f930 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53  ving Statement S
1f940 51 4c 20 7b 48 31 33 31 30 30 7d 20 3c 48 31 33  QL {H13100} <H13
1f950 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  000>.**.** This 
1f960 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
1f970 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
1f980 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
1f990 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
1f9a0 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
1f9b0 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
1f9c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1f9d0 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65   if that stateme
1f9e0 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c  nt was.** compil
1f9f0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
1fa00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fa10 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
1fa20 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1fa30 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
1fa40 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
1fa50 31 30 31 7d 20 49 66 20 74 68 65 20 5b 70 72 65  101} If the [pre
1fa60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1fa70 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 61   passed as the a
1fa80 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20  rgument to.**   
1fa90 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1faa0 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69  sql()] was compi
1fab0 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
1fac0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1fad0 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20  e_v2()] or.**   
1fae0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1faf0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c  prepare16_v2()],
1fb00 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73   then [sqlite3_s
1fb10 71 6c 28 29 5d 20 72 65 74 75 72 6e 73 0a 2a 2a  ql()] returns.**
1fb20 20 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e            a poin
1fb30 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
1fb40 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20  rminated string 
1fb50 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20 55 54 46  containing a UTF
1fb60 2d 38 20 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20  -8 rendering.** 
1fb70 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
1fb80 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 73 74 61  original SQL sta
1fb90 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tement..**.** {H
1fba0 31 33 31 30 32 7d 20 49 66 20 74 68 65 20 5b 70  13102} If the [p
1fbb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1fbc0 74 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65  t] passed as the
1fbd0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
1fbe0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1fbf0 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d  3_sql()] was com
1fc00 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
1fc10 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
1fc20 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  are()] or.**    
1fc30 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
1fc40 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65  repare16()], the
1fc50 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  n [sqlite3_sql()
1fc60 5d 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ] returns a NULL
1fc70 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1fc80 7b 48 31 33 31 30 33 7d 20 54 68 65 20 73 74 72  {H13103} The str
1fc90 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20  ing returned by 
1fca0 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 53 29 5d  [sqlite3_sql(S)]
1fcb0 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
1fcc0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1fcd0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1fce0 65 6e 74 5d 20 53 20 69 73 20 64 65 6c 65 74 65  ent] S is delete
1fcf0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1fd00 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a  _finalize(S)]..*
1fd10 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
1fd20 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
1fd30 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
1fd40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1fd50 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
1fd60 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 20  ed Value Object 
1fd70 7b 48 31 35 30 30 30 7d 20 3c 53 32 30 32 30 30  {H15000} <S20200
1fd80 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
1fd90 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1fda0 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
1fdb0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1fdc0 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
1fdd0 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
1fde0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1fdf0 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
1fe00 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
1fe10 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
1fe20 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
1fe30 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
1fe40 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
1fe50 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
1fe60 69 74 20 73 74 6f 72 65 73 2e 20 56 61 6c 75 65  it stores. Value
1fe70 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
1fe80 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1fe90 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
1fea0 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
1feb0 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
1fec0 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
1fed0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
1fee0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1fef0 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
1ff00 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
1ff10 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
1ff20 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
1ff30 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
1ff40 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1ff50 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
1ff60 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
1ff70 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
1ff80 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
1ff90 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
1ffa0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
1ffb0 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
1ffc0 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
1ffd0 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
1ffe0 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
1fff0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
20000 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
20010 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
20020 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
20030 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
20040 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
20050 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
20060 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
20070 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
20080 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65   A internal mute
20090 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
200a0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
200b0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
200c0 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
200d0 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
200e0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
200f0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
20100 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
20110 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
20120 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
20130 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
20140 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
20150 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
20160 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
20170 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
20180 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
20190 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
201a0 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
201b0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
201c0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
201d0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
201e0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
201f0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
20200 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
20210 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
20220 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
20230 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
20240 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
20250 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
20260 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
20270 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
20280 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
20290 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
202a0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
202b0 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
202c0 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
202d0 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
202e0 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72  tween between pr
202f0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
20300 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
20310 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
20320 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
20330 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
20340 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
20350 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
20360 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
20370 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
20380 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
20390 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
203a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
203b0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
203c0 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
203d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
203e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
203f0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
20400 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
20410 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
20420 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
20430 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
20440 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
20450 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
20460 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
20470 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
20480 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
20490 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
204a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
204b0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
204c0 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
204d0 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
204e0 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
204f0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
20500 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
20510 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
20520 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
20530 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20540 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
20550 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 7b 48  ontext Object {H
20560 31 36 30 30 31 7d 20 3c 53 32 30 32 30 30 3e 0a  16001} <S20200>.
20570 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
20580 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
20590 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
205a0 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
205b0 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
205c0 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
205d0 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
205e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
205f0 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77  object.** is alw
20600 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  ays first parame
20610 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74  ter to [applicat
20620 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
20630 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  functions]..** T
20640 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
20650 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
20660 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
20670 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69  on will pass thi
20680 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72  s.** pointer thr
20690 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20  ough into calls 
206a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
206b0 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  lt_int | sqlite3
206c0 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b  _result()],.** [
206d0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
206e0 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73  e_context()], [s
206f0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
20700 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
20710 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
20720 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  le()], [sqlite3_
20730 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a  get_auxdata()],.
20740 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74  ** and/or [sqlit
20750 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
20760 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
20770 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
20780 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
20790 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
207a0 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56  I3REF: Binding V
207b0 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65  alues To Prepare
207c0 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b 48 31  d Statements {H1
207d0 33 35 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a  3500} <S70300>.*
207e0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
207f0 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
20800 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
20810 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
20820 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
20830 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
20840 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
20850 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
20860 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  nding}.**.** In 
20870 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20  the SQL strings 
20880 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
20890 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
208a0 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
208b0 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
208c0 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
208d0 20 61 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20   a parameter in 
208e0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 66 6f 72  one of these for
208f0 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ms:.**.** <ul>.*
20900 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
20910 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
20920 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
20930 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
20940 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
20950 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   In the paramete
20960 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62  r forms shown ab
20970 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e  ove NNN is an in
20980 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
20990 2a 20 61 6e 64 20 56 56 56 20 69 73 20 61 6e 20  * and VVV is an 
209a0 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 61  alpha-numeric pa
209b0 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 20 54 68  rameter name. Th
209c0 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
209d0 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
209e0 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
209f0 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
20a00 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
20a10 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
20a20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
20a30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
20a40 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
20a50 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54  ed here..**.** T
20a60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
20a70 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
20a80 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
20a90 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
20aa0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
20ab0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
20ac0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
20ad0 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
20ae0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
20af0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
20b00 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
20b10 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
20b20 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51   index of the SQ
20b30 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  L parameter to b
20b40 65 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 6c 65  e set..** The le
20b50 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
20b60 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
20b70 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68  x of 1.  When th
20b80 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
20b90 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
20ba0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
20bb0 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
20bc0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
20bd0 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
20be0 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
20bf0 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
20c00 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 20 69  rrence..** The i
20c10 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
20c20 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
20c30 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
20c40 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
20c50 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
20c60 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
20c70 64 65 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e  desired.  The in
20c80 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e  dex.** for "?NNN
20c90 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  " parameters is 
20ca0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e  the value of NNN
20cb0 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c  ..** The NNN val
20cc0 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
20cd0 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
20ce0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
20cf0 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
20d00 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
20d10 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
20d20 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
20d30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  .**.** The third
20d40 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
20d50 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
20d60 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
20d70 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  .**.** In those 
20d80 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
20d90 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
20da0 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
20db0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
20dc0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
20dd0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
20de0 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
20df0 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
20e00 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
20e10 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
20e20 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
20e30 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
20e40 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
20e50 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  h parameter is n
20e60 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e  egative, the len
20e70 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
20e80 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
20e90 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
20ea0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
20eb0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
20ec0 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61 72 67  ** The fifth arg
20ed0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
20ee0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71  _bind_blob(), sq
20ef0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
20f00 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  ), and.** sqlite
20f10 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
20f20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
20f30 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
20f40 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
20f50 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
20f60 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
20f70 65 64 20 77 69 74 68 20 69 74 2e 20 49 66 20 74  ed with it. If t
20f80 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
20f90 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
20fa0 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
20fb0 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
20fc0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
20fd0 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
20fe0 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
20ff0 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
21000 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
21010 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
21020 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  ed..** If the fi
21030 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
21040 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
21050 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
21060 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
21070 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
21080 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
21090 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
210a0 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
210b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
210c0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
210d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
210e0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
210f0 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
21100 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
21110 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
21120 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
21130 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20  es.  A zeroblob 
21140 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
21150 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
21160 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
21170 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
21180 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
21190 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
211a0 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
211b0 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
211c0 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
211d0 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
211e0 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
211f0 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
21200 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
21210 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
21220 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
21230 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
21240 20 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75   A negative valu
21250 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c  e for the zerobl
21260 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20  ob results in a 
21270 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
21280 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
21290 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
212a0 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
212b0 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73  lled after.** [s
212c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
212d0 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61  2()] (and its va
212e0 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69  riants) or [sqli
212f0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64  te3_reset()] and
21300 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69  .** before [sqli
21310 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
21320 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
21330 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
21340 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
21350 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e  ] routine..** Un
21360 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
21370 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
21380 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
21390 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
213a0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
213b0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
213c0 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66  an error code if
213d0 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65  .** anything goe
213e0 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54  s wrong.  [SQLIT
213f0 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
21400 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
21410 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
21420 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
21430 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20   [SQLITE_NOMEM] 
21440 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
21450 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
21460 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
21470 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
21480 6e 65 64 20 69 66 20 74 68 65 73 65 20 72 6f 75  ned if these rou
21490 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
214a0 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c   on a.** virtual
214b0 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69 73   machine that is
214c0 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65   the wrong state
214d0 20 6f 72 20 77 68 69 63 68 20 68 61 73 20 61 6c   or which has al
214e0 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c  ready been final
214f0 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69  ized..** Detecti
21500 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73 20  on of misuse is 
21510 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 70  unreliable.  App
21520 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
21530 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f   not depend.** o
21540 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  n SQLITE_MISUSE 
21550 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 45  returns.  SQLITE
21560 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65 6e  _MISUSE is inten
21570 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ded to indicate 
21580 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 72  a.** a logic err
21590 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69 63  or in the applic
215a0 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 76  ation.  Future v
215b0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
215c0 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63  e might.** panic
215d0 20 72 61 74 68 65 72 20 74 68 61 6e 20 72 65 74   rather than ret
215e0 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
215f0 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  E..**.** See als
21600 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
21610 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
21620 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
21630 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
21640 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
21650 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
21660 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
21670 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
21680 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 36 7d 20  .**.** {H13506} 
21690 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65 6d 65  The [SQL stateme
216a0 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 72 65 63  nt compiler] rec
216b0 6f 67 6e 69 7a 65 73 20 74 6f 6b 65 6e 73 20 6f  ognizes tokens o
216c0 66 20 74 68 65 20 66 6f 72 6d 73 0a 2a 2a 20 20  f the forms.**  
216d0 20 20 20 20 20 20 20 20 22 3f 22 2c 20 22 3f 4e          "?", "?N
216e0 4e 4e 22 2c 20 22 24 56 56 56 22 2c 20 22 3a 56  NN", "$VVV", ":V
216f0 56 56 22 2c 20 61 6e 64 20 22 40 56 56 56 22 20  VV", and "@VVV" 
21700 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  as SQL parameter
21710 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  s,.**          w
21720 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e 79 20  here NNN is any 
21730 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20  sequence of one 
21740 6f 72 20 6d 6f 72 65 20 64 69 67 69 74 73 0a 2a  or more digits.*
21750 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 77  *          and w
21760 68 65 72 65 20 56 56 56 20 69 73 20 61 6e 79 20  here VVV is any 
21770 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20  sequence of one 
21780 6f 72 20 6d 6f 72 65 20 61 6c 70 68 61 6e 75 6d  or more alphanum
21790 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20  eric.**         
217a0 20 63 68 61 72 61 63 74 65 72 73 20 6f 72 20 22   characters or "
217b0 3a 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66  ::" optionally f
217c0 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20 73 74 72  ollowed by a str
217d0 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a  ing containing.*
217e0 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20 73 70  *          no sp
217f0 61 63 65 73 20 61 6e 64 20 63 6f 6e 74 61 69 6e  aces and contain
21800 65 64 20 77 69 74 68 69 6e 20 70 61 72 65 6e 74  ed within parent
21810 68 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  heses..**.** {H1
21820 33 35 30 39 7d 20 54 68 65 20 69 6e 69 74 69 61  3509} The initia
21830 6c 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51  l value of an SQ
21840 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  L parameter is N
21850 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  ULL..**.** {H135
21860 31 32 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66  12} The index of
21870 20 61 6e 20 22 3f 22 20 53 51 4c 20 70 61 72 61   an "?" SQL para
21880 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6c 61 72  meter is one lar
21890 67 65 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20  ger than the.** 
218a0 20 20 20 20 20 20 20 20 20 6c 61 72 67 65 73 74           largest
218b0 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61   index of SQL pa
218c0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 6c  rameter to the l
218d0 65 66 74 2c 20 6f 72 20 31 20 69 66 0a 2a 2a 20  eft, or 1 if.** 
218e0 20 20 20 20 20 20 20 20 20 74 68 65 20 22 3f 22           the "?"
218f0 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74   is the leftmost
21900 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 2e 0a   SQL parameter..
21910 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 35 7d 20 54  **.** {H13515} T
21920 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22  he index of an "
21930 3f 4e 4e 4e 22 20 53 51 4c 20 70 61 72 61 6d 65  ?NNN" SQL parame
21940 74 65 72 20 69 73 20 74 68 65 20 69 6e 74 65 67  ter is the integ
21950 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48  er NNN..**.** {H
21960 31 33 35 31 38 7d 20 54 68 65 20 69 6e 64 65 78  13518} The index
21970 20 6f 66 20 61 6e 20 22 3a 56 56 56 22 2c 20 22   of an ":VVV", "
21980 24 56 56 56 22 2c 20 6f 72 20 22 40 56 56 56 22  $VVV", or "@VVV"
21990 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
219a0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
219b0 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 69 6e  e same as the in
219c0 64 65 78 20 6f 66 20 6c 65 66 74 6d 6f 73 74 20  dex of leftmost 
219d0 6f 63 63 75 72 72 65 6e 63 65 73 20 6f 66 20 74  occurrences of t
219e0 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he same.**      
219f0 20 20 20 20 70 61 72 61 6d 65 74 65 72 2c 20 6f      parameter, o
21a00 72 20 6f 6e 65 20 6d 6f 72 65 20 74 68 61 6e 20  r one more than 
21a10 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65  the largest inde
21a20 78 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20 20 20  x over all.**   
21a30 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
21a40 73 20 74 6f 20 74 68 65 20 6c 65 66 74 20 69 66  s to the left if
21a50 20 74 68 69 73 20 69 73 20 74 68 65 20 66 69 72   this is the fir
21a60 73 74 20 6f 63 63 75 72 72 65 6e 63 65 0a 2a 2a  st occurrence.**
21a70 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 69            of thi
21a80 73 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20  s parameter, or 
21a90 31 20 69 66 20 74 68 69 73 20 69 73 20 74 68 65  1 if this is the
21aa0 20 6c 65 66 74 6d 6f 73 74 20 70 61 72 61 6d 65   leftmost parame
21ab0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  ter..**.** {H135
21ac0 32 31 7d 20 54 68 65 20 5b 53 51 4c 20 73 74 61  21} The [SQL sta
21ad0 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d  tement compiler]
21ae0 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 5b   fails with an [
21af0 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 0a 2a 2a  SQLITE_RANGE].**
21b00 20 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20            error 
21b10 69 66 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  if the index of 
21b20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
21b30 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31 0a   is less than 1.
21b40 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 67  **          or g
21b50 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
21b60 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 53 51 4c  compile-time SQL
21b70 49 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45  ITE_MAX_VARIABLE
21b80 5f 4e 55 4d 42 45 52 0a 2a 2a 20 20 20 20 20 20  _NUMBER.**      
21b90 20 20 20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a      parameter..*
21ba0 2a 0a 2a 2a 20 7b 48 31 33 35 32 34 7d 20 43 61  *.** {H13524} Ca
21bb0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
21bc0 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69  bind_text | sqli
21bd0 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e  te3_bind(S,N,V,.
21be0 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
21bf0 20 61 73 73 6f 63 69 61 74 65 20 74 68 65 20 76   associate the v
21c00 61 6c 75 65 20 56 20 77 69 74 68 20 61 6c 6c 20  alue V with all 
21c10 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 68  SQL parameters h
21c20 61 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20  aving an.**     
21c30 20 20 20 20 20 69 6e 64 65 78 20 6f 66 20 4e 20       index of N 
21c40 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
21c50 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
21c60 2a 0a 2a 2a 20 7b 48 31 33 35 32 37 7d 20 43 61  *.** {H13527} Ca
21c70 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
21c80 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69  bind_text | sqli
21c90 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e  te3_bind(S,N,...
21ca0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
21cb0 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 63 61  verride prior ca
21cc0 6c 6c 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  lls with the sam
21cd0 65 20 76 61 6c 75 65 73 20 6f 66 20 53 20 61 6e  e values of S an
21ce0 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  d N..**.** {H135
21cf0 33 30 7d 20 42 69 6e 64 69 6e 67 73 20 65 73 74  30} Bindings est
21d00 61 62 6c 69 73 68 65 64 20 62 79 20 5b 73 71 6c  ablished by [sql
21d10 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
21d20 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c   sqlite3_bind(S,
21d30 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
21d40 20 20 70 65 72 73 69 73 74 20 61 63 72 6f 73 73    persist across
21d50 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
21d60 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a  e3_reset(S)]..**
21d70 0a 2a 2a 20 7b 48 31 33 35 33 33 7d 20 49 6e 20  .** {H13533} In 
21d80 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
21d90 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c  3_bind_blob(S,N,
21da0 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,L,D)],.**     
21db0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
21dc0 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c  nd_text(S,N,V,L,
21dd0 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
21de0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
21df0 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
21e00 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64  ,D)] SQLite bind
21e10 73 20 74 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a  s the first L.**
21e20 20 20 20 20 20 20 20 20 20 20 62 79 74 65 73 20            bytes 
21e30 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
21e40 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
21e50 20 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a   by V, when L.**
21e60 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e            is non
21e70 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a  -negative..**.**
21e80 20 7b 48 31 33 35 33 36 7d 20 49 6e 20 63 61 6c   {H13536} In cal
21e90 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
21ea0 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c  ind_text(S,N,V,L
21eb0 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  ,D)] or.**      
21ec0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
21ed0 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
21ee0 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64  ,D)] SQLite bind
21ef0 73 20 63 68 61 72 61 63 74 65 72 73 0a 2a 2a 20  s characters.** 
21f00 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 56 20           from V 
21f10 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
21f20 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
21f30 20 77 68 65 6e 20 4c 20 69 73 20 6e 65 67 61 74   when L is negat
21f40 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  ive..**.** {H135
21f50 33 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  39} In calls to 
21f60 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
21f70 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a  ob(S,N,V,L,D)],.
21f80 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
21f90 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53  ite3_bind_text(S
21fa0 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a  ,N,V,L,D)], or.*
21fb0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
21fc0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
21fd0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e  S,N,V,L,D)] when
21fe0 20 44 20 69 73 20 74 68 65 20 73 70 65 63 69 61   D is the specia
21ff0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  l.**          co
22000 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53  nstant [SQLITE_S
22010 54 41 54 49 43 5d 2c 20 53 51 4c 69 74 65 20 61  TATIC], SQLite a
22020 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
22030 76 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20 20  value V.**      
22040 20 20 20 20 69 73 20 68 65 6c 64 20 69 6e 20 73      is held in s
22050 74 61 74 69 63 20 75 6e 6d 61 6e 61 67 65 64 20  tatic unmanaged 
22060 73 70 61 63 65 20 74 68 61 74 20 77 69 6c 6c 20  space that will 
22070 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20  not change.**   
22080 20 20 20 20 20 20 20 64 75 72 69 6e 67 20 74 68         during th
22090 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68  e lifetime of th
220a0 65 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e binding..**.**
220b0 20 7b 48 31 33 35 34 32 7d 20 49 6e 20 63 61 6c   {H13542} In cal
220c0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
220d0 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  ind_blob(S,N,V,L
220e0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
220f0 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
22100 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
22110 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
22120 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
22130 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
22140 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65 20  ] when D is the 
22150 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20  special.**      
22160 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51      constant [SQ
22170 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
22180 20 74 68 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b   the routine mak
22190 65 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  es a.**         
221a0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
221b0 20 74 68 65 20 76 61 6c 75 65 20 56 20 62 65 66   the value V bef
221c0 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a  ore it returns..
221d0 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 35 7d 20 49  **.** {H13545} I
221e0 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
221f0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c  te3_bind_blob(S,
22200 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20  N,V,L,D)],.**   
22210 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
22220 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
22230 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  L,D)], or.**    
22240 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
22250 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56  ind_text16(S,N,V
22260 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73  ,L,D)] when D is
22270 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
22280 20 20 20 20 20 20 20 20 20 20 61 20 66 75 6e 63            a func
22290 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e 76  tion, SQLite inv
222a0 6f 6b 65 73 20 74 68 61 74 20 66 75 6e 63 74 69  okes that functi
222b0 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79 20 74 68  on to destroy th
222c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  e.**          va
222d0 6c 75 65 20 56 20 61 66 74 65 72 20 69 74 20 68  lue V after it h
222e0 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
222f0 67 20 74 68 65 20 76 61 6c 75 65 20 56 2e 0a 2a  g the value V..*
22300 2a 0a 2a 2a 20 7b 48 31 33 35 34 38 7d 20 49 6e  *.** {H13548} In
22310 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
22320 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
22330 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 76  (S,N,V,L)] the v
22340 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 20  alue bound.**   
22350 20 20 20 20 20 20 20 69 73 20 61 20 42 4c 4f 42         is a BLOB
22360 20 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f 72 20   of L bytes, or 
22370 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
22380 4f 42 20 69 66 20 4c 20 69 73 20 6e 65 67 61 74  OB if L is negat
22390 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  ive..**.** {H135
223a0 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  51} In calls to 
223b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
223c0 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65 20  lue(S,N,V)] the 
223d0 56 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a 2a  V argument may.*
223e0 2a 20 20 20 20 20 20 20 20 20 20 62 65 20 65 69  *          be ei
223f0 74 68 65 72 20 61 20 5b 70 72 6f 74 65 63 74 65  ther a [protecte
22400 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
22410 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a 2a   object or an.**
22420 20 20 20 20 20 20 20 20 20 20 5b 75 6e 70 72 6f            [unpro
22430 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
22440 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  alue] object..*/
22450 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
22460 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
22470 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
22480 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
22490 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
224a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
224b0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
224c0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
224d0 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
224e0 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
224f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
22500 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
22510 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
22520 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
22530 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
22540 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
22550 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
22560 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
22570 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
22580 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
22590 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
225a0 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
225b0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
225c0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
225d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
225e0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
225f0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
22600 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
22610 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
22620 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
22630 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
22640 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
22650 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
22660 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
22670 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
22680 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22690 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
226a0 61 72 61 6d 65 74 65 72 73 20 7b 48 31 33 36 30  arameters {H1360
226b0 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a  0} <S70300>.**.*
226c0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63  * This routine c
226d0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
226e0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
226f0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
22700 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
22710 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
22720 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
22730 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
22740 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
22750 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
22760 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
22770 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
22780 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
22790 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
227a0 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
227b0 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
227c0 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
227d0 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
227e0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ime..**.** This 
227f0 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
22800 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
22810 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
22820 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
22830 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
22840 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
22850 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
22860 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
22870 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
22880 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
22890 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
228a0 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72  s of the ?NNN ar
228b0 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
228c0 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
228d0 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20  the list..**.** 
228e0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
228f0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
22900 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
22910 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
22920 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
22930 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
22940 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
22950 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _index()]..**.**
22960 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
22970 2a 2a 20 7b 48 31 33 36 30 31 7d 20 54 68 65 20  ** {H13601} The 
22980 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
22990 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 53 29  rameter_count(S)
229a0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
229b0 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
229c0 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65  the largest inde
229d0 78 20 6f 66 20 61 6c 6c 20 53 51 4c 20 70 61 72  x of all SQL par
229e0 61 6d 65 74 65 72 73 20 69 6e 20 74 68 65 0a 2a  ameters in the.*
229f0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
22a00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
22a10 53 2c 20 6f 72 20 30 20 69 66 20 53 20 63 6f 6e  S, or 0 if S con
22a20 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72  tains no SQL par
22a30 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20  ameters..*/.int 
22a40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
22a50 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c  ameter_count(sql
22a60 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
22a70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
22a80 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72  me Of A Host Par
22a90 61 6d 65 74 65 72 20 7b 48 31 33 36 32 30 7d 20  ameter {H13620} 
22aa0 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S70300>.**.** T
22ab0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
22ac0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
22ad0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
22ae0 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61   n-th.** [SQL pa
22af0 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 20 5b 70  rameter] in a [p
22b00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22b10 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  t]..** SQL param
22b20 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
22b30 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  m "?NNN" or ":AA
22b40 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
22b50 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61  "$AAA".** have a
22b60 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74   name which is t
22b70 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22  he string "?NNN"
22b80 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
22b90 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
22ba0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  * respectively..
22bb0 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
22bc0 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
22bd0 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
22be0 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e   or "?".** is in
22bf0 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
22c00 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50  f the name..** P
22c10 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
22c20 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
22c30 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
22c40 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
22c50 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c  me.** and are al
22c60 73 6f 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  so referred to a
22c70 73 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  s "anonymous par
22c80 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
22c90 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
22ca0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
22cb0 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
22cc0 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  0..**.** If the 
22cd0 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f  value n is out o
22ce0 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
22cf0 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e n-th parameter
22d00 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
22d10 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
22d20 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74  turned.  The ret
22d30 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
22d40 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
22d50 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
22d60 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
22d70 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
22d80 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
22d90 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
22da0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22db0 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
22dc0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
22dd0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
22de0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
22df0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
22e00 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
22e10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
22e20 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
22e30 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
22e40 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
22e50 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ndex()]..**.** I
22e60 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
22e70 20 7b 48 31 33 36 32 31 7d 20 54 68 65 20 5b 73   {H13621} The [s
22e80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
22e90 6d 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d  meter_name(S,N)]
22ea0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
22eb0 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ns.**          a
22ec0 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
22ed0 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   of the name of 
22ee0 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
22ef0 72 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  r in.**         
22f00 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
22f10 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 76 69  tatement] S havi
22f20 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a  ng index N, or.*
22f30 2a 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  *          NULL 
22f40 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 53  if there is no S
22f50 51 4c 20 70 61 72 61 6d 65 74 65 72 20 77 69 74  QL parameter wit
22f60 68 20 69 6e 64 65 78 20 4e 20 6f 72 20 69 66 20  h index N or if 
22f70 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
22f80 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69  parameter with i
22f90 6e 64 65 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f  ndex N is an ano
22fa0 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
22fb0 20 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63   "?"..*/.const c
22fc0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
22fd0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
22fe0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
22ff0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
23000 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
23010 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
23020 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48   A Given Name {H
23030 31 33 36 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a  13640} <S70300>.
23040 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65  **.** Return the
23050 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
23060 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
23070 20 69 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a   its name.  The.
23080 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
23090 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
230a0 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
230b0 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
230c0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
230d0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
230e0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41  ite3_bind()].  A
230f0 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
23100 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
23110 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
23120 20 66 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 72   found.  The par
23130 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
23140 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
23150 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
23160 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
23170 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
23180 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
23190 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
231a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
231b0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
231c0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
231d0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
231e0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
231f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
23200 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
23210 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
23220 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
23230 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  dex()]..**.** IN
23240 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
23250 7b 48 31 33 36 34 31 7d 20 54 68 65 20 5b 73 71  {H13641} The [sq
23260 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
23270 65 74 65 72 5f 69 6e 64 65 78 28 53 2c 4e 29 5d  eter_index(S,N)]
23280 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
23290 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ns.**          t
232a0 68 65 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20  he index of SQL 
232b0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
232c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
232d0 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ment].**        
232e0 20 20 53 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d    S whose name m
232f0 61 74 63 68 65 73 20 74 68 65 20 55 54 46 2d 38  atches the UTF-8
23300 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20   string N, or 0 
23310 69 66 20 74 68 65 72 65 20 69 73 0a 2a 2a 20 20  if there is.**  
23320 20 20 20 20 20 20 20 20 6e 6f 20 6d 61 74 63 68          no match
23330 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
23340 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
23350 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
23360 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
23370 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
23380 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
23390 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
233a0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
233b0 6d 65 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c 53  ment {H13660} <S
233c0 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e  70300>.**.** Con
233d0 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
233e0 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
233f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
23400 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
23410 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
23420 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
23430 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
23440 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23450 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f  ..** Use this ro
23460 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61  utine to reset a
23470 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  ll host paramete
23480 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  rs to NULL..**.*
23490 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
234a0 0a 2a 2a 20 7b 48 31 33 36 36 31 7d 20 54 68 65  .** {H13661} The
234b0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
234c0 62 69 6e 64 69 6e 67 73 28 53 29 5d 20 69 6e 74  bindings(S)] int
234d0 65 72 66 61 63 65 20 72 65 73 65 74 73 20 61 6c  erface resets al
234e0 6c 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20  l SQL.**        
234f0 20 20 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64    parameter bind
23500 69 6e 67 73 20 69 6e 20 74 68 65 20 5b 70 72 65  ings in the [pre
23510 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23520 20 53 20 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e   S back to NULL.
23530 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
23540 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
23550 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
23560 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23570 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
23580 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
23590 74 20 7b 48 31 33 37 31 30 7d 20 3c 53 31 30 37  t {H13710} <S107
235a0 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  00>.**.** Return
235b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
235c0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
235d0 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
235e0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
235f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23600 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  . This routine r
23610 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d  eturns 0 if pStm
23620 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73  t is an SQL.** s
23630 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
23640 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
23650 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
23660 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
23670 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
23680 2a 2a 0a 2a 2a 20 7b 48 31 33 37 31 31 7d 20 54  **.** {H13711} T
23690 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
236a0 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74  mn_count(S)] int
236b0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
236c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
236d0 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73           columns
236e0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
236f0 65 74 20 67 65 6e 65 72 61 74 65 64 20 62 79 20  et generated by 
23700 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
23710 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20  atement] S,.**  
23720 20 20 20 20 20 20 20 20 6f 72 20 30 20 69 66 20          or 0 if 
23730 53 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72  S does not gener
23740 61 74 65 20 61 20 72 65 73 75 6c 74 20 73 65 74  ate a result set
23750 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
23760 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
23770 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
23780 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
23790 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
237a0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
237b0 74 20 7b 48 31 33 37 32 30 7d 20 3c 53 31 30 37  t {H13720} <S107
237c0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
237d0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
237e0 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
237f0 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
23800 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
23810 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
23820 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
23830 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  ement.  The sqli
23840 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
23850 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
23860 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
23870 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
23880 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
23890 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
238a0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
238b0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
238c0 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
238d0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
238e0 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20  16 string.  The 
238f0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
23900 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
23910 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
23920 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
23930 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
23940 65 6d 65 6e 74 2e 20 54 68 65 20 73 65 63 6f 6e  ement. The secon
23950 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
23960 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d  he.** column num
23970 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f  ber.  The leftmo
23980 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
23990 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ber 0..**.** The
239a0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
239b0 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
239c0 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
239d0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
239e0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
239f0 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
23a00 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
23a10 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
23a20 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
23a30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
23a40 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
23a50 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
23a60 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
23a70 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74  ..**.** If sqlit
23a80 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
23a90 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
23aa0 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
23ab0 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
23ac0 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
23ad0 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
23ae0 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
23af0 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
23b00 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
23b10 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
23b20 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
23b30 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
23b40 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
23b50 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
23b60 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
23b70 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
23b80 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
23b90 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
23ba0 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
23bb0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
23bc0 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
23bd0 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
23be0 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
23bf0 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
23c00 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20  the next..**.** 
23c10 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
23c20 2a 20 7b 48 31 33 37 32 31 7d 20 41 20 73 75 63  * {H13721} A suc
23c30 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
23c40 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
23c50 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53  e3_column_name(S
23c60 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,N)].**         
23c70 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
23c80 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ns the name of t
23c90 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77  he Nth column (w
23ca0 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20  here 0 is.**    
23cb0 20 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f        the leftmo
23cc0 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74  st column) for t
23cd0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
23ce0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
23cf0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23d00 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72  ment] S as a zer
23d10 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
23d20 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
23d30 20 7b 48 31 33 37 32 33 7d 20 41 20 73 75 63 63   {H13723} A succ
23d40 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
23d50 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
23d60 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
23d70 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,N)].**        
23d80 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75    interface retu
23d90 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  rns the name of 
23da0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28  the Nth column (
23db0 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20  where 0 is.**   
23dc0 20 20 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d         the leftm
23dd0 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20  ost column) for 
23de0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
23df0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
23e00 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
23e10 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65  ement] S as a ze
23e20 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
23e30 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 20  F-16 string.**  
23e40 20 20 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e          in the n
23e50 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
23e60 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 34 7d  ..**.** {H13724}
23e70 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
23e80 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64  lumn_name()] and
23e90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
23ea0 5f 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20  _name16()].**   
23eb0 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
23ec0 73 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20  s return a NULL 
23ed0 70 6f 69 6e 74 65 72 20 69 66 20 74 68 65 79 20  pointer if they 
23ee0 61 72 65 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a  are unable to.**
23ef0 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61            alloca
23f00 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
23f10 64 20 74 68 65 69 72 20 6e 6f 72 6d 61 6c 20 72  d their normal r
23f20 65 74 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a  eturn strings..*
23f30 2a 0a 2a 2a 20 7b 48 31 33 37 32 35 7d 20 49 66  *.** {H13725} If
23f40 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
23f50 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
23f60 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f  umn_name(S,N)] o
23f70 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
23f80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
23f90 6d 65 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75  me16(S,N)] is ou
23fa0 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 6e  t of range, then
23fb0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
23fc0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75   interfaces retu
23fd0 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  rn a NULL pointe
23fe0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 36  r..**.** {H13726
23ff0 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  } The strings re
24000 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
24010 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53  e3_column_name(S
24020 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ,N)] and.**     
24030 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
24040 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  lumn_name16(S,N)
24050 5d 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  ] are valid unti
24060 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20  l the next.**   
24070 20 20 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65         call to e
24080 69 74 68 65 72 20 72 6f 75 74 69 6e 65 20 77 69  ither routine wi
24090 74 68 20 74 68 65 20 73 61 6d 65 20 53 20 61 6e  th the same S an
240a0 64 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  d N parameters.*
240b0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e  *          or un
240c0 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  til [sqlite3_fin
240d0 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c  alize(S)] is cal
240e0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  led..**.** {H137
240f0 32 37 7d 20 57 68 65 6e 20 61 20 72 65 73 75 6c  27} When a resul
24100 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53  t column of a [S
24110 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
24120 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20   contains.**    
24130 20 20 20 20 20 20 61 6e 20 41 53 20 63 6c 61 75        an AS clau
24140 73 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  se, the name of 
24150 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  that column is t
24160 68 65 20 69 64 65 6e 74 69 66 69 65 72 0a 2a 2a  he identifier.**
24170 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65            to the
24180 20 72 69 67 68 74 20 6f 66 20 74 68 65 20 41 53   right of the AS
24190 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e   keyword..*/.con
241a0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
241b0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
241c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
241d0 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
241e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
241f0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
24200 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
24210 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
24220 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
24230 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b  A Query Result {
24240 48 31 33 37 34 30 7d 20 3c 53 31 30 37 30 30 3e  H13740} <S10700>
24250 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
24260 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
24270 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
24280 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f  ne what column o
24290 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20  f what.** table 
242a0 69 6e 20 77 68 69 63 68 20 64 61 74 61 62 61 73  in which databas
242b0 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20  e a result of a 
242c0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
242d0 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a  nt comes from..*
242e0 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * The name of th
242f0 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
24300 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
24310 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
24320 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
24330 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
24340 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62  ing.  The _datab
24350 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
24360 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
24370 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
24380 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
24390 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
243a0 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
243b0 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
243c0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
243d0 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68  lumn name..** Th
243e0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
243f0 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
24400 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
24410 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
24420 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
24430 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
24440 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
24450 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
24460 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
24470 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
24480 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
24490 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  ..**.** The name
244a0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
244b0 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
244c0 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
244d0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
244e0 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
244f0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  mn..**.** The fi
24500 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
24510 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
24520 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  lls is a [prepar
24530 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
24540 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
24550 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
24560 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
24570 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
24580 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61  ed by.** the sta
24590 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
245a0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
245b0 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
245c0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74  .**.** If the Nt
245d0 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
245e0 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
245f0 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
24600 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
24610 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
24620 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
24630 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
24640 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
24650 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65  .** NULL.  These
24660 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
24670 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
24680 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
24690 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
246a0 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69  occurs.  Otherwi
246b0 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
246c0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
246d0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
246e0 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20  e, table.** and 
246f0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
24700 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
24710 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
24720 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74  om..**.** As wit
24730 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
24740 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70  te APIs, those p
24750 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 22 31  ostfixed with "1
24760 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
24770 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
24780 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66  ngs, the other f
24790 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
247a0 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  UTF-8. {END}.**.
247b0 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 61 72  ** These APIs ar
247c0 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
247d0 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
247e0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
247f0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
24800 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
24810 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
24820 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64  ocessor symbol d
24830 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41  efined..**.** {A
24840 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f  13751}.** If two
24850 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
24860 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
24870 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
24880 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
24890 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
248a0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
248b0 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
248c0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
248d0 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
248e0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
248f0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
24900 2a 20 7b 48 31 33 37 34 31 7d 20 54 68 65 20 5b  * {H13741} The [
24910 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
24920 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e  atabase_name(S,N
24930 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
24940 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
24950 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
24960 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
24970 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  d name of the da
24980 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63  tabase from whic
24990 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  h the.**        
249a0 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c    Nth result col
249b0 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70  umn of the [prep
249c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
249d0 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a  S is extracted,.
249e0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e  **          or N
249f0 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
24a00 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20  olumn of S is a 
24a10 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
24a20 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  on.**          o
24a30 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
24a40 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
24a50 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
24a60 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 32 7d  ..**.** {H13742}
24a70 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
24a80 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
24a90 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  me16(S,N)] inter
24aa0 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
24ab0 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
24ac0 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76  the UTF-16 nativ
24ad0 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72  e byte order zer
24ae0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
24af0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
24b00 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72  e.**          fr
24b10 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74 68  om which the Nth
24b20 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
24b30 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
24b40 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a  statement] S is.
24b50 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 74 72  **          extr
24b60 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69  acted, or NULL i
24b70 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
24b80 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72   of S is a gener
24b90 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  al expression.**
24ba0 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20            or if 
24bb0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
24bc0 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f  te memory to sto
24bd0 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a  re the name..**.
24be0 2a 2a 20 7b 48 31 33 37 34 33 7d 20 54 68 65 20  ** {H13743} The 
24bf0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
24c00 74 61 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d  table_name(S,N)]
24c10 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
24c20 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
24c30 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20        the UTF-8 
24c40 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
24c50 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c  name of the tabl
24c60 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  e from which the
24c70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
24c80 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
24c90 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
24ca0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20  statement] S is 
24cb0 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20  extracted,.**   
24cc0 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69         or NULL i
24cd0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
24ce0 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72   of S is a gener
24cf0 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  al expression.**
24d00 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20            or if 
24d10 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
24d20 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f  te memory to sto
24d30 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a  re the name..**.
24d40 2a 2a 20 7b 48 31 33 37 34 34 7d 20 54 68 65 20  ** {H13744} The 
24d50 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
24d60 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e  table_name16(S,N
24d70 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
24d80 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
24d90 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
24da0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
24db0 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  rder zero-termin
24dc0 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  ated name of the
24dd0 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20   table.**       
24de0 20 20 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68     from which th
24df0 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
24e00 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70  umn of the [prep
24e10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
24e20 53 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  S is.**         
24e30 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e   extracted, or N
24e40 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
24e50 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20  olumn of S is a 
24e60 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
24e70 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  on.**          o
24e80 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
24e90 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
24ea0 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
24eb0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 35 7d  ..**.** {H13745}
24ec0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
24ed0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
24ee0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
24ef0 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
24f00 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
24f10 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
24f20 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68  nated name of th
24f30 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66  e table column f
24f40 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a  rom which the.**
24f50 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65            Nth re
24f60 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  sult column of t
24f70 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
24f80 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74  tement] S is ext
24f90 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20  racted,.**      
24fa0 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74      or NULL if t
24fb0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
24fc0 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20   S is a general 
24fd0 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20  expression.**   
24fe0 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61         or if una
24ff0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
25000 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20  memory to store 
25010 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  the name..**.** 
25020 7b 48 31 33 37 34 36 7d 20 54 68 65 20 5b 73 71  {H13746} The [sq
25030 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
25040 67 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  gin_name16(S,N)]
25050 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
25060 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
25070 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36        the UTF-16
25080 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
25090 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  er zero-terminat
250a0 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74  ed name of the t
250b0 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  able.**         
250c0 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69   column from whi
250d0 63 68 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ch the Nth resul
250e0 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  t column of the.
250f0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
25100 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25110 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c   S is extracted,
25120 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
25130 4e 74 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20  Nth column.**   
25140 20 20 20 20 20 20 20 6f 66 20 53 20 69 73 20 61         of S is a
25150 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73   general express
25160 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65  ion or if unable
25170 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
25180 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ory.**          
25190 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d  to store the nam
251a0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 38  e..**.** {H13748
251b0 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  } The return val
251c0 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20  ues from.**     
251d0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
251e0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
251f0 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
25200 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
25210 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
25220 20 76 61 6c 69 64 20 66 6f 72 20 74 68 65 20 6c   valid for the l
25230 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 5b  ifetime of the [
25240 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25250 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nt].**          
25260 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 65 6e 63  or until the enc
25270 6f 64 69 6e 67 20 69 73 20 63 68 61 6e 67 65 64  oding is changed
25280 20 62 79 20 61 6e 6f 74 68 65 72 20 6d 65 74 61   by another meta
25290 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  data.**         
252a0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20   interface call 
252b0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 70 72 65  for the same pre
252c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
252d0 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
252e0 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a  * ASSUMPTIONS:.*
252f0 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 20 49 66  *.** {A13751} If
25300 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
25310 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
25320 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20   more.**        
25330 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
25340 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
25350 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
25360 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
25370 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 74 68            for th
25380 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
25390 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
253a0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
253b0 20 20 20 20 20 20 20 20 20 20 61 74 20 74 68 65            at the
253c0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
253d0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
253e0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f  undefined..*/.co
253f0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
25400 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
25410 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
25420 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
25430 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
25440 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
25450 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
25460 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
25470 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
25480 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
25490 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
254a0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
254b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
254c0 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
254d0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
254e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
254f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
25500 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
25510 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
25520 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
25530 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
25540 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
25550 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
25560 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
25570 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
25580 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31  Query Result {H1
25590 33 37 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  3760} <S10700>.*
255a0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
255b0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
255c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
255d0 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
255e0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
255f0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
25600 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
25610 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
25620 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
25630 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
25640 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
25650 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
25660 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
25670 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
25680 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
25690 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
256a0 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
256b0 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 63  d.  If the Nth c
256c0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
256d0 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
256e0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
256f0 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
25700 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
25710 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65  returned..** The
25720 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
25730 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
25740 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a   encoded. {END}.
25750 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
25760 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
25770 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
25780 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
25790 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
257a0 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
257b0 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
257c0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
257d0 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
257e0 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
257f0 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
25800 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
25810 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
25820 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
25830 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
25840 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
25850 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
25860 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
25870 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
25880 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51  (i==0)..**.** SQ
25890 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
258a0 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
258b0 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61  g.  So just beca
258c0 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
258d0 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
258e0 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
258f0 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
25900 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
25910 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
25920 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
25930 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
25940 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
25950 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
25960 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
25970 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
25980 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65  ot static.  Type
25990 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
259a0 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
259b0 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
259c0 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
259d0 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
259e0 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
259f0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
25a00 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 31 7d  :.**.** {H13761}
25a10 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63    A successful c
25a20 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
25a30 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
25a40 53 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 0a  S,N)] returns a.
25a50 2a 2a 20 20 20 20 20 20 20 20 20 20 20 7a 65 72  **           zer
25a60 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
25a70 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  -8 string contai
25a80 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61 72 65  ning the declare
25a90 64 20 64 61 74 61 74 79 70 65 0a 2a 2a 20 20 20  d datatype.**   
25aa0 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 74          of the t
25ab0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
25ac0 20 61 70 70 65 61 72 73 20 61 73 20 74 68 65 20   appears as the 
25ad0 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62  Nth column (numb
25ae0 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ered.**         
25af0 20 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65    from 0) of the
25b00 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74   result set to t
25b10 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
25b20 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a  tement] S..**.**
25b30 20 7b 48 31 33 37 36 32 7d 20 20 41 20 73 75 63   {H13762}  A suc
25b40 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
25b50 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
25b60 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d  decltype16(S,N)]
25b70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
25b80 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72  turns a zero-ter
25b90 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e  minated UTF-16 n
25ba0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
25bb0 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20   string.**      
25bc0 20 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20       containing 
25bd0 74 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 74  the declared dat
25be0 61 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62  atype of the tab
25bf0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61  le column that a
25c00 70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20  ppears.**       
25c10 20 20 20 20 61 73 20 74 68 65 20 4e 74 68 20 63      as the Nth c
25c20 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20  olumn (numbered 
25c30 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72  from 0) of the r
25c40 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65  esult set to the
25c50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70  .**           [p
25c60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25c70 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  t] S..**.** {H13
25c80 37 36 33 7d 20 20 49 66 20 4e 20 69 73 20 6c 65  763}  If N is le
25c90 73 73 20 74 68 61 6e 20 30 20 6f 72 20 4e 20 69  ss than 0 or N i
25ca0 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f  s greater than o
25cb0 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20  r equal to.**   
25cc0 20 20 20 20 20 20 20 20 74 68 65 20 6e 75 6d 62          the numb
25cd0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
25ce0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
25cf0 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20  tatement] S,.** 
25d00 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20            or if 
25d10 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
25d20 66 20 53 20 69 73 20 61 6e 20 65 78 70 72 65 73  f S is an expres
25d30 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
25d40 20 72 61 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   rather.**      
25d50 20 20 20 20 20 74 68 61 6e 20 61 20 74 61 62 6c       than a tabl
25d60 65 20 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69 66 20  e column, or if 
25d70 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
25d80 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a 20 20  ion failure.**  
25d90 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 20           occurs 
25da0 64 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20  during encoding 
25db0 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74 68 65  conversions, the
25dc0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63  n.**           c
25dd0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
25de0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
25df0 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  (S,N)] or.**    
25e00 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
25e10 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
25e20 36 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 20 4e  6(S,N)] return N
25e30 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ULL..*/.const ch
25e40 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
25e50 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
25e60 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
25e70 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
25e80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
25e90 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
25ea0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
25eb0 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
25ec0 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
25ed0 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d 20 3c 53  ment {H13200} <S
25ee0 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74  10000>.**.** Aft
25ef0 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
25f00 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
25f10 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
25f20 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
25f30 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
25f40 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
25f50 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
25f60 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
25f70 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
25f80 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
25f90 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
25fa0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
25fb0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
25fc0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
25fd0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
25fe0 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
25ff0 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
26000 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
26010 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
26020 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
26030 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
26040 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
26050 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
26060 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
26070 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
26080 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
26090 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
260a0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
260b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
260c0 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
260d0 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
260e0 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
260f0 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
26100 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
26110 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
26120 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
26130 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
26140 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
26150 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
26160 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
26170 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
26180 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
26190 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
261a0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
261b0 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
261c0 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
261d0 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
261e0 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
261f0 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
26200 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
26210 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
26220 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57  TE_MISUSE]..** W
26230 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
26240 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
26250 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
26260 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
26270 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
26280 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
26290 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
262a0 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  .**.** [SQLITE_B
262b0 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
262c0 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
262d0 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
262e0 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
262f0 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
26300 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
26310 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20  ts job.  If the 
26320 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
26330 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
26340 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
26350 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
26360 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
26370 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
26380 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
26390 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
263a0 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
263b0 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
263c0 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69  hin a.** explici
263d0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
263e0 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
263f0 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
26400 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
26410 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
26420 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
26430 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
26440 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
26450 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
26460 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
26470 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
26480 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
26490 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
264a0 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
264b0 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
264c0 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
264d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
264e0 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
264f0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
26500 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
26510 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
26520 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
26530 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
26540 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
26550 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
26560 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
26570 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
26580 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
26590 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
265a0 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
265b0 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
265c0 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
265d0 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
265e0 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
265f0 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
26600 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
26610 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
26620 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
26630 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
26640 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
26650 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
26660 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
26670 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
26680 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
26690 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
266a0 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
266b0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
266c0 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
266d0 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
266e0 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
266f0 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
26700 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
26710 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69  errmsg()]..** Wi
26720 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
26730 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
26740 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
26750 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
26760 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
26770 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
26780 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
26790 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
267a0 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
267b0 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
267c0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
267d0 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
267e0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
267f0 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68  atement].  In th
26800 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
26810 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
26820 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
26830 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
26840 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
26850 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
26860 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
26870 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
26880 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
26890 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
268a0 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
268b0 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
268c0 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
268d0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
268e0 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
268f0 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
26900 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
26910 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
26920 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75  t had.** previou
26930 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
26940 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
26950 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
26960 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
26970 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
26980 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
26990 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
269a0 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
269b0 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
269c0 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
269d0 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
269e0 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
269f0 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
26a00 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63  /b> In the legac
26a10 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
26a20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a   sqlite3_step().
26a30 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  ** API always re
26a40 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
26a50 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c  error code, [SQL
26a60 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
26a70 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72  owing any.** err
26a80 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
26a90 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
26aa0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
26ab0 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a    You must call.
26ac0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
26ad0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
26ae0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
26af0 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
26b00 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63  e of the.** spec
26b10 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
26b20 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
26b30 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
26b40 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
26b50 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
26b60 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
26b70 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
26b80 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
26b90 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
26ba0 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
26bb0 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
26bc0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
26bd0 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ** using either 
26be0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26bf0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
26c00 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
26c10 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
26c20 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
26c30 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
26c40 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
26c50 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66  pare16()] interf
26c60 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  aces,.** then th
26c70 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
26c80 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72  [error codes] ar
26c90 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  e returned direc
26ca0 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  tly.** by sqlite
26cb0 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75  3_step().  The u
26cc0 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69  se of the "v2" i
26cd0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
26ce0 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mmended..**.** I
26cf0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
26d00 20 7b 48 31 33 32 30 32 7d 20 20 49 66 20 74 68   {H13202}  If th
26d10 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
26d20 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65 61 64  ement] S is read
26d30 79 20 74 6f 20 62 65 20 72 75 6e 2c 20 74 68 65  y to be run, the
26d40 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  n.**           [
26d50 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
26d60 20 61 64 76 61 6e 63 65 73 20 74 68 61 74 20 70   advances that p
26d70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26d80 74 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20  t until.**      
26d90 20 20 20 20 20 63 6f 6d 70 6c 65 74 69 6f 6e 20       completion 
26da0 6f 72 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72  or until it is r
26db0 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 20 61  eady to return a
26dc0 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68  nother row of th
26dd0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  e.**           r
26de0 65 73 75 6c 74 20 73 65 74 2c 20 6f 72 20 75 6e  esult set, or un
26df0 74 69 6c 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  til an [sqlite3_
26e00 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65  interrupt | inte
26e10 72 72 75 70 74 5d 0a 2a 2a 20 20 20 20 20 20 20  rrupt].**       
26e20 20 20 20 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d      or a run-tim
26e30 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
26e40 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 34 7d 20 20  **.** {H15304}  
26e50 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b  When a call to [
26e60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
26e70 20 63 61 75 73 65 73 20 74 68 65 20 5b 70 72 65   causes the [pre
26e80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26e90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 53 20  .**           S 
26ea0 74 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65  to run to comple
26eb0 74 69 6f 6e 2c 20 74 68 65 20 66 75 6e 63 74 69  tion, the functi
26ec0 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  on returns [SQLI
26ed0 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_DONE]..**.** 
26ee0 7b 48 31 35 33 30 36 7d 20 20 57 68 65 6e 20 61  {H15306}  When a
26ef0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
26f00 33 5f 73 74 65 70 28 53 29 5d 20 73 74 6f 70 73  3_step(S)] stops
26f10 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 72   because it is r
26f20 65 61 64 79 20 74 6f 0a 2a 2a 20 20 20 20 20 20  eady to.**      
26f30 20 20 20 20 20 72 65 74 75 72 6e 20 61 6e 6f 74       return anot
26f40 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65 20 72  her row of the r
26f50 65 73 75 6c 74 20 73 65 74 2c 20 69 74 20 72 65  esult set, it re
26f60 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f  turns [SQLITE_RO
26f70 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30  W]..**.** {H1530
26f80 38 7d 20 20 49 66 20 61 20 63 61 6c 6c 20 74 6f  8}  If a call to
26f90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
26fa0 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e  )] encounters an
26fb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
26fc0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
26fd0 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 20 6f 72   | interrupt] or
26fe0 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
26ff0 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  r,.**           
27000 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  it returns an ap
27010 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20  propriate error 
27020 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e 6f 74  code that is not
27030 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20   one of.**      
27040 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d       [SQLITE_OK]
27050 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
27060 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
27070 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 31 30 7d  ..**.** {H15310}
27080 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33    If an [sqlite3
27090 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74  _interrupt | int
270a0 65 72 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e  errupt] or a run
270b0 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20  -time error.**  
270c0 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 20           occurs 
270d0 64 75 72 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  during a call to
270e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
270f0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  )].**           
27100 66 6f 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  for a [prepared 
27110 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 63 72 65  statement] S cre
27120 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ated using.**   
27130 20 20 20 20 20 20 20 20 6c 65 67 61 63 79 20 69          legacy i
27140 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
27150 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
27160 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
27170 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
27180 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 75  ()], then the fu
27190 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 65  nction returns e
271a0 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
271b0 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52     [SQLITE_ERROR
271c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
271d0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
271e0 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  USE]..*/.int sql
271f0 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
27200 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
27210 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
27220 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
27230 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b 48 31  a result set {H1
27240 33 37 37 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  3770} <S10700>.*
27250 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 68 65  *.** Returns the
27260 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65   number of value
27270 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  s in the current
27280 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
27290 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e  lt set..**.** IN
272a0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
272b0 7b 48 31 33 37 37 31 7d 20 20 41 66 74 65 72 20  {H13771}  After 
272c0 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
272d0 65 33 5f 73 74 65 70 28 53 29 5d 20 74 68 61 74  e3_step(S)] that
272e0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
272f0 5f 52 4f 57 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  _ROW],.**       
27300 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33      the [sqlite3
27310 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20  _data_count(S)] 
27320 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74  routine will ret
27330 75 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c  urn the same val
27340 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ue.**           
27350 61 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  as the [sqlite3_
27360 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d  column_count(S)]
27370 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
27380 20 7b 48 31 33 37 37 32 7d 20 20 41 66 74 65 72   {H13772}  After
27390 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
273a0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
273b0 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
273c0 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  than.**         
273d0 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f    [SQLITE_ROW] o
273e0 72 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65  r before [sqlite
273f0 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 62  3_step(S)] has b
27400 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68  een called on th
27410 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  e.**           [
27420 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27430 6e 74 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  nt] for the firs
27440 74 20 74 69 6d 65 20 73 69 6e 63 65 20 69 74 20  t time since it 
27450 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  was.**          
27460 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
27470 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 6f 72  e | prepared] or
27480 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 20   [sqlite3_reset 
27490 7c 20 72 65 73 65 74 5d 2c 0a 2a 2a 20 20 20 20  | reset],.**    
274a0 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69         the [sqli
274b0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53  te3_data_count(S
274c0 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
274d0 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20  ns zero..*/.int 
274e0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
274f0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
27500 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
27510 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
27520 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 20  ental Datatypes 
27530 7b 48 31 30 32 36 35 7d 20 3c 53 31 30 31 31 30  {H10265} <S10110
27540 3e 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59  ><S10120>.** KEY
27550 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
27560 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36  XT.**.** {H10266
27570 7d 20 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  } Every value in
27580 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
27590 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
275a0 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
275b0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
275c0 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
275d0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
275e0 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
275f0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
27600 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
27610 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
27620 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
27630 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ul> {END}.**.** 
27640 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
27650 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
27660 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
27670 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
27680 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
27690 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
276a0 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
276b0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
276c0 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
276d0 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
276e0 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
276f0 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
27700 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
27710 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
27720 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
27730 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
27740 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
27750 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
27760 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
27770 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
27780 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
27790 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
277a0 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
277b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
277c0 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
277d0 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
277e0 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
277f0 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
27800 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
27810 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
27820 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
27830 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
27840 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
27850 20 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b 48   From A Query {H
27860 31 33 38 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a  13800} <S10700>.
27870 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
27880 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
27890 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
278a0 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
278b0 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
278c0 20 71 75 65 72 79 22 20 69 6e 74 65 72 66 61 63   query" interfac
278d0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e..**.** These r
278e0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
278f0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
27900 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
27910 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
27920 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  ** result row of
27930 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76   a query.  In ev
27940 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
27950 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
27960 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
27970 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
27980 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
27990 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
279a0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
279b0 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
279c0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
279d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
279e0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
279f0 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
27a00 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
27a10 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
27a20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
27a30 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
27a40 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
27a50 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
27a60 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63    The leftmost c
27a70 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
27a80 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
27a90 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49  index 0..**.** I
27aa0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
27ab0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
27ac0 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
27ad0 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
27ae0 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
27af0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
27b00 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
27b10 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
27b20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
27b30 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
27b40 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
27b50 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
27b60 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
27b70 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
27b80 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
27b90 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
27ba0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
27bb0 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
27bc0 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
27bd0 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
27be0 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
27bf0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
27c00 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
27c10 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
27c20 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
27c30 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
27c40 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
27c50 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
27c60 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
27c70 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
27c80 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
27c90 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
27ca0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
27cb0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
27cc0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
27cd0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
27ce0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
27cf0 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
27d00 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
27d10 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
27d20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
27d30 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
27d40 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
27d50 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
27d60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
27d70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
27d80 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
27d90 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
27da0 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
27db0 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
27dc0 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
27dd0 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
27de0 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68  sult column.  Th
27df0 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
27e00 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
27e10 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
27e20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
27e30 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
27e40 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
27e50 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20   [SQLITE_NULL]. 
27e60 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   The value.** re
27e70 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
27e80 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
27e90 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
27ea0 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a  ul if no type.**
27eb0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
27ec0 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65  e occurred as de
27ed0 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20  scribed below.  
27ee0 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e  After a type con
27ef0 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20  version,.** the 
27f00 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
27f10 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
27f20 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66  _type() is undef
27f30 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a  ined.  Future.**
27f40 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
27f50 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74  ite may change t
27f60 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
27f70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
27f80 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  pe().** followin
27f90 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  g a type convers
27fa0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ion..**.** If th
27fb0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
27fc0 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
27fd0 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
27fe0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
27ff0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
28000 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
28010 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
28020 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
28030 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  ..** If the resu
28040 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
28050 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
28060 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28070 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
28080 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
28090 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
280a0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
280b0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74  f bytes..** If t
280c0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
280d0 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
280e0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
280f0 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
28100 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
28110 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
28120 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
28130 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
28140 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
28150 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
28160 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
28170 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65  .** The value re
28180 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20  turned does not 
28190 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
281a0 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74   terminator at t
281b0 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
281c0 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c   string.  For cl
281d0 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
281e0 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65   returned is the
281f0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
28200 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
28210 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
28220 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
28230 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72  .**.** Strings r
28240 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
28250 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
28260 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
28270 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
28280 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
28290 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
282a0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e  zero terminated.
282b0 20 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20    The return.** 
282c0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
282d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
282e0 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
282f0 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72  th BLOB is an ar
28300 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74  bitrary.** point
28310 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65  er, possibly eve
28320 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
28330 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
28340 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28350 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  16() routine is 
28360 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74  similar to sqlit
28370 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
28380 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20  ).** but leaves 
28390 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54  the result in UT
283a0 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62  F-16 in native b
283b0 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61  yte order instea
283c0 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54  d of UTF-8..** T
283d0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
283e0 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64  or is not includ
283f0 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74  ed in this count
28400 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65  ..**.** The obje
28410 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ct returned by [
28420 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
28430 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a  alue()] is an.**
28440 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
28450 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
28460 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65  ect.  An unprote
28470 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
28480 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79  ue object.** may
28490 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
284a0 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  th [sqlite3_bind
284b0 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
284c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
284d0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
284e0 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
284f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
28500 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
28510 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
28520 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
28530 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
28540 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
28550 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
28560 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
28570 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
28580 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
28590 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
285a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
285b0 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68  ytes()], then th
285c0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
285d0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
285e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
285f0 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
28600 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
28610 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46   appropriate.  F
28620 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
28630 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
28640 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
28650 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
28660 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
28670 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
28680 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
28690 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
286a0 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
286b0 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
286c0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54  utomatically.  T
286d0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
286e0 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
286f0 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
28700 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
28710 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
28720 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
28730 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
28740 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
28750 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
28760 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
28770 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
28780 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
28790 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
287a0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
287b0 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
287c0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
287d0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
287e0 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
287f0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
28800 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
28810 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
28820 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
28830 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
28840 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
28850 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
28860 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
28870 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
28880 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
28890 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
288a0 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
288b0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
288c0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
288d0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
288e0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
288f0 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
28900 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
28910 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
28920 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
28930 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
28940 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
28950 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
28960 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
28970 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65   float to intege
28980 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  r.** <tr><td>  F
28990 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
289a0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
289b0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
289c0 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
289d0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
289e0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
289f0 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e   Same as FLOAT->
28a00 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
28a10 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
28a20 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73  NTEGER   <td> Us
28a30 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
28a40 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
28a50 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
28a60 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  > Use atof().** 
28a70 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
28a80 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
28a90 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
28aa0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
28ab0 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
28ac0 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
28ad0 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
28ae0 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
28af0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
28b00 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
28b10 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
28b20 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28  T then use atof(
28b30 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
28b40 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
28b50 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
28b60 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
28b70 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
28b80 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
28b90 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
28ba0 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61  e table above ma
28bb0 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f  kes reference to
28bc0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
28bd0 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74  ary functions at
28be0 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66  oi().** and atof
28bf0 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73  ().  SQLite does
28c00 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20   not really use 
28c10 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
28c20 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20    It has its.** 
28c30 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69  own equivalent i
28c40 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73  nternal routines
28c50 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e  .  The atoi() an
28c60 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61  d atof() names a
28c70 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68  re.** used in th
28c80 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76  e table for brev
28c90 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20  ity and because 
28ca0 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61  they are familia
28cb0 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70  r to most.** C p
28cc0 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a  rogrammers..**.*
28cd0 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
28ce0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
28cf0 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
28d00 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
28d10 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
28d20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
28d30 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
28d40 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
28d50 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
28d60 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
28d70 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
28d80 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  ed..** Type conv
28d90 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
28da0 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
28db0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
28dc0 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
28dd0 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
28de0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
28df0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
28e00 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
28e10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
28e20 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
28e30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
28e40 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
28e50 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
28e60 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
28e70 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
28e80 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
28e90 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
28ea0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
28eb0 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
28ec0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
28ed0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
28ee0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
28ef0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
28f00 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
28f10 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
28f20 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
28f30 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
28f40 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
28f50 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
28f60 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
28f70 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
28f80 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
28f90 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
28fa0 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
28fb0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
28fc0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
28fd0 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
28fe0 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
28ff0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65  /ul>.**.** Conve
29000 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
29010 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
29020 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
29030 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
29040 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
29050 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
29060 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
29070 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
29080 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
29090 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
290a0 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69  rior pointer poi
290b0 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65  nts to will have
290c0 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
290d0 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
290e0 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
290f0 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
29100 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
29110 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
29120 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
29130 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
29140 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
29150 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
29160 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
29170 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20  *.** The safest 
29180 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72  and easiest to r
29190 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69  emember policy i
291a0 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
291b0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
291c0 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
291d0 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
291e0 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  * <ul>.**  <li>s
291f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
29200 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
29210 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29220 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
29230 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
29240 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
29250 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
29260 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
29270 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
29280 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
29290 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
292a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
292b0 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
292c0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
292d0 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
292e0 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
292f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
29300 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  ),.** sqlite3_co
29310 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20  lumn_blob(), or 
29320 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
29330 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
29340 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
29350 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65  t.** into the de
29360 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68  sired format, th
29370 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
29380 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
29390 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
293a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
293b0 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  to find the size
293c0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
293d0 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
293e0 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
293f0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
29400 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29410 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
29420 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
29430 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
29440 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78  , and do not mix
29450 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
29460 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
29470 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20  ).** with calls 
29480 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
29490 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a  n_bytes()..**.**
294a0 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   The pointers re
294b0 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64  turned are valid
294c0 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f   until a type co
294d0 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20  nversion occurs 
294e0 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20  as.** described 
294f0 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20  above, or until 
29500 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
29510 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
29520 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
29530 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
29540 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
29550 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
29560 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
29570 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
29580 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
29590 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
295a0 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
295b0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
295c0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
295d0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
295e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
295f0 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
29600 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
29610 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  e()]..**.** If a
29620 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
29630 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
29640 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
29650 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
29660 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
29670 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
29680 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
29690 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
296a0 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
296b0 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
296c0 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
296d0 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
296e0 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
296f0 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
29700 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
29710 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
29720 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
29730 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
29740 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
29750 0a 2a 2a 20 7b 48 31 33 38 30 33 7d 20 54 68 65  .** {H13803} The
29760 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
29770 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65  _blob(S,N)] inte
29780 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
29790 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
297a0 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
297b0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
297c0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
297d0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  or.**          t
297e0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
297f0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
29800 20 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e 20 72   BLOB and then r
29810 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20  eturns a.**     
29820 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20       pointer to 
29830 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61  the converted va
29840 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  lue..**.** {H138
29850 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  06} The [sqlite3
29860 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c  _column_bytes(S,
29870 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
29880 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
29890 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
298a0 62 79 74 65 73 20 69 6e 20 74 68 65 20 42 4c 4f  bytes in the BLO
298b0 42 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63  B or string (exc
298c0 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a  lusive of the.**
298d0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
298e0 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65  erminator on the
298f0 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61   string) that wa
29900 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
29910 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f  e.**          mo
29920 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
29930 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
29940 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a  n_blob(S,N)] or.
29950 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
29960 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29970 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  (S,N)]..**.** {H
29980 31 33 38 30 39 7d 20 54 68 65 20 5b 73 71 6c 69  13809} The [sqli
29990 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
299a0 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
299b0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ce returns the.*
299c0 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
299d0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
299e0 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73  e string (exclus
299f0 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ive of the.**   
29a00 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d         zero term
29a10 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74  inator on the st
29a20 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72  ring) that was r
29a30 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
29a40 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20  *          most 
29a50 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
29a60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
29a70 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a  ext16(S,N)]..**.
29a80 2a 2a 20 7b 48 31 33 38 31 32 7d 20 54 68 65 20  ** {H13812} The 
29a90 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
29aa0 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74  double(S,N)] int
29ab0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
29ac0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
29ad0 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
29ae0 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
29af0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
29b00 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
29b10 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
29b20 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
29b30 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
29b40 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20   value and.**   
29b50 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61         returns a
29b60 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61   copy of that va
29b70 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  lue..**.** {H138
29b80 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  15} The [sqlite3
29b90 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29  _column_int(S,N)
29ba0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
29bb0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
29bc0 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
29bd0 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
29be0 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
29bf0 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20   set for the.** 
29c00 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
29c10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
29c20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69  into a 64-bit si
29c30 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
29c40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
29c50 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33  urns the lower 3
29c60 32 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69  2 bits of that i
29c70 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nteger..**.** {H
29c80 31 33 38 31 38 7d 20 54 68 65 20 5b 73 71 6c 69  13818} The [sqli
29c90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
29ca0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
29cb0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
29cc0 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
29cd0 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
29ce0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
29cf0 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68  esult set for th
29d00 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
29d10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29d20 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62  t] S into a 64-b
29d30 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
29d40 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  r and.**        
29d50 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79    returns a copy
29d60 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
29d70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 31 7d  ..**.** {H13821}
29d80 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
29d90 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20  lumn_text(S,N)] 
29da0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
29db0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
29dc0 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
29dd0 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
29de0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
29df0 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
29e00 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64     the [prepared
29e10 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
29e20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
29e30 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20  ated UTF-8.**   
29e40 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
29e50 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
29e60 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
29e70 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32  ng..**.** {H1382
29e80 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
29e90 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c  column_text16(S,
29ea0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
29eb0 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
29ec0 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
29ed0 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
29ee0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
29ef0 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a  lt set for the.*
29f00 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
29f10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29f20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  S into a zero-te
29f30 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a  rminated 2-byte.
29f40 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67  **          alig
29f50 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76  ned UTF-16 nativ
29f60 65 20 62 79 74 65 20 6f 72 64 65 72 20 73 74 72  e byte order str
29f70 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
29f80 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 6f  **          a po
29f90 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
29fa0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ring..**.** {H13
29fb0 38 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  827} The [sqlite
29fc0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c  3_column_type(S,
29fd0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
29fe0 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
29ff0 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45    one of [SQLITE
2a000 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NULL], [SQLITE_
2a010 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54  INTEGER], [SQLIT
2a020 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20  E_FLOAT],.**    
2a030 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45        [SQLITE_TE
2a040 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  XT], or [SQLITE_
2a050 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72  BLOB] as appropr
2a060 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  iate for.**     
2a070 20 20 20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c       the Nth col
2a080 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
2a090 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2a0a0 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20  sult set for.** 
2a0b0 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72           the [pr
2a0c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a0d0 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  ] S..**.** {H138
2a0e0 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  30} The [sqlite3
2a0f0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c  _column_value(S,
2a100 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
2a110 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20  turns a.**      
2a120 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61      pointer to a
2a130 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
2a140 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2a150 6a 65 63 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ject for the.** 
2a160 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
2a170 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
2a180 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2a190 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20  sult set for.** 
2a1a0 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72           the [pr
2a1b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a1c0 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ] S..*/.const vo
2a1d0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2a1e0 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
2a1f0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2a200 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2a210 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
2a220 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2a230 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2a240 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2a250 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a260 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
2a270 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a280 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
2a290 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2a2a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2a2b0 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
2a2c0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2a2d0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
2a2e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2a2f0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
2a300 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
2a310 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
2a320 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2a330 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
2a340 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2a350 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2a360 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2a370 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
2a380 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2a390 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2a3a0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
2a3b0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2a3c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
2a3d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2a3e0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
2a3f0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
2a400 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2a410 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
2a420 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
2a430 63 74 20 7b 48 31 33 33 30 30 7d 20 3c 53 37 30  ct {H13300} <S70
2a440 33 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a  300><S30100>.**.
2a450 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66  ** The sqlite3_f
2a460 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
2a470 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2a480 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
2a490 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2a4a0 2a 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65  * If the stateme
2a4b0 6e 74 20 77 61 73 20 65 78 65 63 75 74 65 64 20  nt was executed 
2a4c0 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 72 20  successfully or 
2a4d0 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 20  not executed at 
2a4e0 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  all, then.** SQL
2a4f0 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e  ITE_OK is return
2a500 65 64 2e 20 49 66 20 65 78 65 63 75 74 69 6f 6e  ed. If execution
2a510 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
2a520 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e  t failed then an
2a530 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
2a540 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
2a550 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
2a560 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  urned..**.** Thi
2a570 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
2a580 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
2a590 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20  oint during the 
2a5a0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
2a5b0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2a5c0 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68  atement].  If th
2a5d0 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  e virtual machin
2a5e0 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d  e has not.** com
2a5f0 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
2a600 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   when this routi
2a610 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  ne is called, th
2a620 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e  at is like.** en
2a630 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72  countering an er
2a640 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74  ror or an [sqlit
2a650 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69  e3_interrupt | i
2a660 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e  nterrupt]..** In
2a670 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73  complete updates
2a680 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62   may be rolled b
2a690 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74  ack and transact
2a6a0 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a  ions canceled,.*
2a6b0 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  * depending on t
2a6c0 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  he circumstances
2a6d0 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72  , and the.** [er
2a6e0 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e  ror code] return
2a6f0 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49  ed will be [SQLI
2a700 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a  TE_ABORT]..**.**
2a710 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2a720 2a 2a 20 7b 48 31 31 33 30 32 7d 20 54 68 65 20  ** {H11302} The 
2a730 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2a740 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(S)] interface 
2a750 64 65 73 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20  destroys the.** 
2a760 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
2a770 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2a780 61 6e 64 20 72 65 6c 65 61 73 65 73 20 61 6c 6c  and releases all
2a790 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d  .**          mem
2a7a0 6f 72 79 20 61 6e 64 20 66 69 6c 65 20 72 65 73  ory and file res
2a7b0 6f 75 72 63 65 73 20 68 65 6c 64 20 62 79 20 74  ources held by t
2a7c0 68 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  hat object..**.*
2a7d0 2a 20 7b 48 31 31 33 30 34 7d 20 49 66 20 74 68  * {H11304} If th
2a7e0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2a7f0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2a800 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
2a810 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
2a820 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a830 20 53 20 72 65 74 75 72 6e 65 64 20 61 6e 20 65   S returned an e
2a840 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20  rror,.**        
2a850 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
2a860 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72 65 74  finalize(S)] ret
2a870 75 72 6e 73 20 74 68 61 74 20 73 61 6d 65 20 65  urns that same e
2a880 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rror..*/.int sql
2a890 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
2a8a0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2a8b0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2a8c0 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
2a8d0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2a8e0 4f 62 6a 65 63 74 20 7b 48 31 33 33 33 30 7d 20  Object {H13330} 
2a8f0 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S70300>.**.** T
2a900 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
2a910 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
2a920 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
2a930 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a940 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
2a950 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2a960 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
2a970 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
2a980 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73  ed..** Any SQL s
2a990 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c  tatement variabl
2a9a0 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75  es that had valu
2a9b0 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d  es bound to them
2a9c0 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
2a9d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2a9e0 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
2a9f0 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20  *() API] retain 
2aa00 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a  their values..**
2aa10 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   Use [sqlite3_cl
2aa20 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20  ear_bindings()] 
2aa30 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e  to reset the bin
2aa40 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  dings..**.** {H1
2aa50 31 33 33 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  1332} The [sqlit
2aa60 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
2aa70 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
2aa80 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2aa90 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20  ement] S.**     
2aaa0 20 20 20 20 20 62 61 63 6b 20 74 6f 20 74 68 65       back to the
2aab0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
2aac0 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
2aad0 20 7b 48 31 31 33 33 34 7d 20 49 66 20 74 68 65   {H11334} If the
2aae0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2aaf0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2ab00 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
2ab10 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2ab20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ab30 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
2ab40 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
2ab50 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20  TE_DONE],.**    
2ab60 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71 6c        or if [sql
2ab70 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
2ab80 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
2ab90 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
2aba0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2abb0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
2abc0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
2abd0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
2abe0 7b 48 31 31 33 33 36 7d 20 49 66 20 74 68 65 20  {H11336} If the 
2abf0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2ac00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2ac10 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
2ac20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
2ac30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2ac40 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
2ac50 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  ror, then.**    
2ac60 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
2ac70 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
2ac80 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
2ac90 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
2aca0 0a 2a 2a 20 7b 48 31 31 33 33 38 7d 20 54 68 65  .** {H11338} The
2acb0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2acc0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
2acd0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
2ace0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20  e values.**     
2acf0 20 20 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c       of any [sql
2ad00 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
2ad10 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
2ad20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ad30 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
2ad40 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
2ad50 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2ad60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ad70 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
2ad80 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
2ad90 69 6f 6e 73 20 7b 48 31 36 31 30 30 7d 20 3c 53  ions {H16100} <S
2ada0 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  20200>.** KEYWOR
2adb0 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
2adc0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
2add0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2ade0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2adf0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
2ae00 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2ae10 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2ae20 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2ae30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77  }.**.** These tw
2ae40 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  o functions (col
2ae50 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
2ae60 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
2ae70 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
2ae80 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
2ae90 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
2aea0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
2aeb0 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
2aec0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
2aed0 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
2aee0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
2aef0 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
2af00 79 20 64 69 66 66 65 72 65 6e 63 65 20 62 65 74  y difference bet
2af10 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20  ween the.** two 
2af20 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  is that the seco
2af30 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  nd parameter, th
2af40 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73  e name of the (s
2af50 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20  calar) function 
2af60 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c  or.** aggregate,
2af70 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55   is encoded in U
2af80 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33  TF-8 for sqlite3
2af90 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2afa0 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a  () and UTF-16.**
2afb0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
2afc0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2afd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
2afe0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
2aff0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2b000 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
2b010 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
2b020 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
2b030 64 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67  dded.  If a sing
2b040 6c 65 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20  le program uses 
2b050 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61  more than one da
2b060 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
2b070 74 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c  tion internally,
2b080 20 74 68 65 6e 20 53 51 4c 20 66 75 6e 63 74 69   then SQL functi
2b090 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  ons must be adde
2b0a0 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74  d individually t
2b0b0 6f 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62 61  o.** each databa
2b0c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a  se connection..*
2b0d0 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
2b0e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2b0f0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
2b100 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2b110 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
2b120 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20 6c 65  defined.  The le
2b130 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
2b140 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
2b150 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73  55 bytes, exclus
2b160 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65  ive of.** the ze
2b170 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
2b180 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
2b190 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  me length limit 
2b1a0 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74  is in bytes, not
2b1b0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20  .** characters. 
2b1c0 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
2b1d0 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
2b1e0 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
2b1f0 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
2b200 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45  ult in [SQLITE_E
2b210 52 52 4f 52 5d 20 62 65 69 6e 67 20 72 65 74 75  RROR] being retu
2b220 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
2b230 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2b240 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
2b250 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
2b260 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2b270 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
2b280 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20   takes. If this 
2b290 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67  parameter is neg
2b2a0 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
2b2b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2b2c0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
2b2d0 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
2b2e0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a   of arguments..*
2b2f0 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  *.** The fourth 
2b300 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
2b310 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
2b320 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
2b330 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
2b340 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
2b350 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
2b360 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
2b370 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66  ters.  Any SQL f
2b380 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2b390 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  tation should be
2b3a0 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
2b3b0 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38   work with UTF-8
2b3c0 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55  , UTF-16le, or U
2b3d0 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f  TF-16be.  But so
2b3e0 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  me implementatio
2b3f0 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72  ns may be.** mor
2b400 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68  e efficient with
2b410 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68   one encoding th
2b420 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20  an another.  It 
2b430 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a  is allowed to.**
2b440 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
2b450 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2b460 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
2b470 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2b480 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d   multiple.** tim
2b490 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  es with the same
2b4a0 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69   function but wi
2b4b0 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c  th different val
2b4c0 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e  ues of eTextRep.
2b4d0 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c  .** When multipl
2b4e0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2b4f0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
2b500 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
2b510 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
2b520 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
2b530 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
2b540 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
2b550 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
2b560 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ion..** If there
2b570 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c   is only a singl
2b580 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2b590 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20   which does not 
2b5a0 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a  care what text.*
2b5b0 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  * encoding is us
2b5c0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ed, then the fou
2b5d0 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rth argument sho
2b5e0 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  uld be [SQLITE_A
2b5f0 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  NY]..**.** The f
2b600 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
2b610 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
2b620 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
2b630 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
2b640 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
2b650 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
2b660 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
2b670 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
2b680 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a  er_data()]..**.*
2b690 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65  * The seventh, e
2b6a0 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20  ighth and ninth 
2b6b0 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
2b6c0 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
2b6d0 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
2b6e0 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
2b6f0 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
2b700 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
2b710 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2b720 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 41 20  ** aggregate. A 
2b730 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
2b740 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
2b750 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2b760 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
2b770 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55  allback only, NU
2b780 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75  LL pointers shou
2b790 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73 20  ld be passed as 
2b7a0 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46  the xStep and xF
2b7b0 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65  inal.** paramete
2b7c0 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65  rs. An aggregate
2b7d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
2b7e0 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
2b7f0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65  entation of xSte
2b800 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
2b810 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20  and NULL should 
2b820 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46  be passed for xF
2b830 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61  unc. To delete a
2b840 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51  n existing.** SQ
2b850 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
2b860 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
2b870 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  LL for all three
2b880 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
2b890 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  cks..**.** It is
2b8a0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
2b8b0 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
2b8c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2b8d0 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
2b8e0 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
2b8f0 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
2b900 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
2b910 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
2b920 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
2b930 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65   differing prefe
2b940 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
2b950 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ngs.  SQLite wil
2b960 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
2b970 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74  lementation most
2b980 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
2b990 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
2b9a0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
2b9b0 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ction is used..*
2b9c0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2b9d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 33 7d 20  .**.** {H16103} 
2b9e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
2b9f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2ba00 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 68 61  ] interface beha
2ba10 76 65 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20  ves exactly.**  
2ba20 20 20 20 20 20 20 20 20 6c 69 6b 65 20 5b 73 71          like [sq
2ba30 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2ba40 63 74 69 6f 6e 28 29 5d 20 69 6e 20 65 76 65 72  ction()] in ever
2ba50 79 20 77 61 79 20 65 78 63 65 70 74 20 74 68 61  y way except tha
2ba60 74 20 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  t it.**         
2ba70 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
2ba80 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 20 61 72  zFunctionName ar
2ba90 67 75 6d 65 6e 74 20 61 73 20 7a 65 72 6f 2d 74  gument as zero-t
2baa0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36  erminated UTF-16
2bab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 74  .**          nat
2bac0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
2bad0 6e 73 74 65 61 64 20 6f 66 20 61 73 20 7a 65 72  nstead of as zer
2bae0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
2baf0 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30  -8..**.** {H1610
2bb00 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  6} A successful 
2bb10 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a  invocation of.**
2bb20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73            the [s
2bb30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2bb40 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e  nction(D,X,N,E,.
2bb50 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ..)] interface r
2bb60 65 67 69 73 74 65 72 73 0a 2a 2a 20 20 20 20 20  egisters.**     
2bb70 20 20 20 20 20 6f 72 20 72 65 70 6c 61 63 65 73       or replaces
2bb80 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2bb90 6f 6e 73 20 69 6e 20 74 68 65 20 5b 64 61 74 61  ons in the [data
2bba0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2bbb0 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75   D.**          u
2bbc0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
2bbd0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2bbe0 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 4e  n named X with N
2bbf0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20   parameters.**  
2bc00 20 20 20 20 20 20 20 20 61 6e 64 20 68 61 76 69          and havi
2bc10 6e 67 20 61 20 70 72 65 66 65 72 72 65 64 20 74  ng a preferred t
2bc20 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  ext encoding of 
2bc30 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 39  E..**.** {H16109
2bc40 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
2bc50 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2bc60 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2bc70 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
2bc80 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  ].**          re
2bc90 70 6c 61 63 65 73 20 74 68 65 20 50 2c 20 46 2c  places the P, F,
2bca0 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65 73   S, and L values
2bcb0 20 66 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72 20   from any prior 
2bcc0 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20  calls with.**   
2bcd0 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20         the same 
2bce0 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20 76  D, X, N, and E v
2bcf0 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  alues..**.** {H1
2bd00 36 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  6112} The [sqlit
2bd10 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2bd20 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74  on(D,X,...)] int
2bd30 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
2bd40 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  h.**          a 
2bd50 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b  return code of [
2bd60 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
2bd70 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2bd80 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20 20  n name X is.**  
2bd90 20 20 20 20 20 20 20 20 6c 6f 6e 67 65 72 20 74          longer t
2bda0 68 61 6e 20 32 35 35 20 62 79 74 65 73 20 65 78  han 255 bytes ex
2bdb0 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
2bdc0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
2bdd0 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 38 7d 20 45  **.** {H16118} E
2bde0 69 74 68 65 72 20 46 20 6d 75 73 74 20 62 65 20  ither F must be 
2bdf0 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c  NULL and S and L
2be00 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72   are non-NULL or
2be10 20 65 6c 73 65 20 46 0a 2a 2a 20 20 20 20 20 20   else F.**      
2be20 20 20 20 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20      is non-NULL 
2be30 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20  and S and L are 
2be40 4e 55 4c 4c 2c 20 6f 74 68 65 72 77 69 73 65 0a  NULL, otherwise.
2be50 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2be60 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2be70 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  tion(D,X,N,E,P,F
2be80 2c 53 2c 4c 29 5d 20 72 65 74 75 72 6e 73 20 5b  ,S,L)] returns [
2be90 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a  SQLITE_ERROR]..*
2bea0 2a 0a 2a 2a 20 7b 48 31 36 31 32 31 7d 20 54 68  *.** {H16121} Th
2beb0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2bec0 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e  e_function(D,...
2bed0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  )] interface fai
2bee0 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20  ls with an.**   
2bef0 20 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f 64         error cod
2bf00 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42 55 53  e of [SQLITE_BUS
2bf10 59 5d 20 69 66 20 74 68 65 72 65 20 65 78 69 73  Y] if there exis
2bf20 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  t [prepared stat
2bf30 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20 20 20  ements].**      
2bf40 20 20 20 20 61 73 73 6f 63 69 61 74 65 64 20 77      associated w
2bf50 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
2bf60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e  e connection] D.
2bf70 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 34 7d 20  .**.** {H16124} 
2bf80 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
2bf90 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2bfa0 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ,N,...)] interfa
2bfb0 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  ce fails with an
2bfc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 72  .**          err
2bfd0 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  or code of [SQLI
2bfe0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 70 61 72  TE_ERROR] if par
2bff0 61 6d 65 74 65 72 20 4e 20 28 73 70 65 63 69 66  ameter N (specif
2c000 79 69 6e 67 20 74 68 65 20 6e 75 6d 62 65 72 0a  ying the number.
2c010 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61  **          of a
2c020 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
2c030 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  SQL function bei
2c040 6e 67 20 72 65 67 69 73 74 65 72 65 64 29 20 69  ng registered) i
2c050 73 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 20  s less.**       
2c060 20 20 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72     than -1 or gr
2c070 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 2e 0a  eater than 127..
2c080 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 37 7d 20 57  **.** {H16127} W
2c090 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67  hen N is non-neg
2c0a0 61 74 69 76 65 2c 20 74 68 65 20 5b 73 71 6c 69  ative, the [sqli
2c0b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2c0c0 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a  ion(D,X,N,...)].
2c0d0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
2c0e0 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61 6c  rface causes cal
2c0f0 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76  lbacks to be inv
2c100 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c  oked for the SQL
2c110 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
2c120 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 68        named X wh
2c130 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  en the number of
2c140 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
2c150 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
2c160 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78  s.**          ex
2c170 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b  actly N..**.** {
2c180 48 31 36 31 33 30 7d 20 57 68 65 6e 20 4e 20 69  H16130} When N i
2c190 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c 69 74  s -1, the [sqlit
2c1a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2c1b0 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a  on(D,X,N,...)].*
2c1c0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
2c1d0 66 61 63 65 20 63 61 75 73 65 73 20 63 61 6c 6c  face causes call
2c1e0 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f  backs to be invo
2c1f0 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c 20  ked for the SQL 
2c200 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  function.**     
2c210 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 69 74       named X wit
2c220 68 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  h any number of 
2c230 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
2c240 20 7b 48 31 36 31 33 33 7d 20 57 68 65 6e 20 63   {H16133} When c
2c250 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2c260 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c270 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20  (D,X,N,...)].** 
2c280 20 20 20 20 20 20 20 20 20 73 70 65 63 69 66 79           specify
2c290 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
2c2a0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
2c2b0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58   same function X
2c2c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
2c2d0 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d   when one implem
2c2e0 65 6e 74 61 74 69 6f 6e 20 68 61 73 20 4e 3e 3d  entation has N>=
2c2f0 30 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  0 and the other 
2c300 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20  has N=(-1).**   
2c310 20 20 20 20 20 20 20 74 68 65 20 69 6d 70 6c 65         the imple
2c320 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
2c330 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 69 73 20 70   non-zero N is p
2c340 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  referred..**.** 
2c350 7b 48 31 36 31 33 36 7d 20 57 68 65 6e 20 63 61  {H16136} When ca
2c360 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2c370 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2c380 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a  D,X,N,E,...)].**
2c390 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69 66            specif
2c3a0 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  y multiple imple
2c3b0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
2c3c0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2c3d0 58 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  X with.**       
2c3e0 20 20 20 74 68 65 20 73 61 6d 65 20 6e 75 6d 62     the same numb
2c3f0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2c400 4e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  N but with diffe
2c410 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  rent.**         
2c420 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74 68   encodings E, th
2c430 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  en the implement
2c440 61 74 69 6f 6e 20 77 68 65 72 65 20 45 20 6d 61  ation where E ma
2c450 74 63 68 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  tches the.**    
2c460 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20 65        database e
2c470 6e 63 6f 64 69 6e 67 20 69 73 20 70 72 65 66 65  ncoding is prefe
2c480 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  rred..**.** {H16
2c490 31 33 39 7d 20 46 6f 72 20 61 6e 20 61 67 67 72  139} For an aggr
2c4a0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2c4b0 6f 6e 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  on created using
2c4c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2c4d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2c4e0 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
2c4f0 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e 61  0,S,L)] the fina
2c500 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  lizer.**        
2c510 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20 77 69 6c    function L wil
2c520 6c 20 61 6c 77 61 79 73 20 62 65 20 69 6e 76 6f  l always be invo
2c530 6b 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  ked exactly once
2c540 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   if the.**      
2c550 20 20 20 20 73 74 65 70 20 66 75 6e 63 74 69 6f      step functio
2c560 6e 20 53 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  n S is called on
2c570 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
2c580 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 34 32 7d 20  .**.** {H16142} 
2c590 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
2c5a0 6b 65 73 20 65 69 74 68 65 72 20 74 68 65 20 78  kes either the x
2c5b0 46 75 6e 63 20 6f 72 20 78 53 74 65 70 20 66 75  Func or xStep fu
2c5c0 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20  nction of.**    
2c5d0 20 20 20 20 20 20 61 6e 20 61 70 70 6c 69 63 61        an applica
2c5e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2c5f0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
2c600 72 65 67 61 74 65 20 63 72 65 61 74 65 64 0a 2a  regate created.*
2c610 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 5b 73  *          by [s
2c620 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2c630 6e 63 74 69 6f 6e 28 29 5d 20 6f 72 20 5b 73 71  nction()] or [sq
2c640 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2c650 63 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20  ction16()],.**  
2c660 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65          then the
2c670 20 61 72 72 61 79 20 6f 66 20 5b 73 71 6c 69 74   array of [sqlit
2c680 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2c690 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  s passed as the.
2c6a0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 69 72  **          thir
2c6b0 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
2c6c0 61 6c 77 61 79 73 20 5b 70 72 6f 74 65 63 74 65  always [protecte
2c6d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2c6e0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74   objects..*/.int
2c6f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2c700 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
2c710 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
2c720 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
2c730 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
2c740 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2c750 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
2c760 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
2c770 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2c780 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2c790 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2c7a0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
2c7b0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2c7c0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2c7d0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
2c7e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2c7f0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2c800 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2c810 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
2c820 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
2c830 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2c840 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2c850 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2c860 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2c870 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2c880 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2c890 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2c8a0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2c8b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2c8c0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2c8d0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2c8e0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2c8f0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a  context*).);../*
2c900 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
2c910 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 48 31  xt Encodings {H1
2c920 30 32 36 37 7d 20 3c 53 35 30 32 30 30 3e 20 3c  0267} <S50200> <
2c930 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  H16100>.**.** Th
2c940 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
2c950 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
2c960 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
2c970 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
2c980 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
2c990 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
2c9a0 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
2c9b0 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
2c9c0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
2c9d0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
2c9e0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
2c9f0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
2ca00 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
2ca10 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
2ca20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
2ca30 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2ca40 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
2ca50 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
2ca60 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69      5    /* sqli
2ca70 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ca80 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  ion only */.#def
2ca90 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2caa0 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
2cab0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
2cac0 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
2cad0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
2cae0 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
2caf0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
2cb00 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
2cb10 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
2cb20 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
2cb30 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
2cb40 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
2cb50 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
2cb60 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
2cb70 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2cb80 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
2cb90 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
2cba0 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
2cbb0 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
2cbc0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
2cbd0 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
2cbe0 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65  ions.  To help e
2cbf0 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20  ncourage people 
2cc00 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e  to avoid.** usin
2cc10 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  g these function
2cc20 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f  s, we are not go
2cc30 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20  ing to tell you 
2cc40 77 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  want they do..*/
2cc50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67  .int sqlite3_agg
2cc60 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
2cc70 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2cc80 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
2cc90 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
2cca0 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2ccb0 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
2ccc0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
2ccd0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
2cce0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f  .int sqlite3_glo
2ccf0 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64  bal_recover(void
2cd00 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2cd10 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76  thread_cleanup(v
2cd20 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
2cd30 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
2cd40 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2cd50 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
2cd60 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
2cd70 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t64);../*.** CAP
2cd80 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67  I3REF: Obtaining
2cd90 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61   SQL Function Pa
2cda0 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b  rameter Values {
2cdb0 48 31 35 31 30 30 7d 20 3c 53 32 30 32 30 30 3e  H15100} <S20200>
2cdc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
2cdd0 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
2cde0 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
2cdf0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
2ce00 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
2ce10 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
2ce20 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
2ce30 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
2ce40 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
2ce50 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
2ce60 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a   aggregate..**.*
2ce70 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
2ce80 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
2ce90 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
2cea0 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
2ceb0 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
2cec0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2ced0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
2cee0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2cef0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
2cf00 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
2cf10 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
2cf20 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
2cf30 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
2cf40 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61  .** The 4th para
2cf50 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
2cf60 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
2cf70 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
2cf80 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
2cf90 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2cfa0 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
2cfb0 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
2cfc0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
2cfd0 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
2cfe0 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
2cff0 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
2d000 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
2d010 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
2d020 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
2d030 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2d040 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
2d050 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
2d060 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
2d070 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d080 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2d090 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
2d0a0 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
2d0b0 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
2d0c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d0d0 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
2d0e0 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
2d0f0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
2d100 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2d110 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
2d120 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
2d130 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
2d140 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
2d150 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
2d160 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2d170 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70  take a single [p
2d180 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d190 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
2d1a0 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  * pointer instea
2d1b0 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  d of a [sqlite3_
2d1c0 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61  stmt*] pointer a
2d1d0 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  nd an integer co
2d1e0 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  lumn number..**.
2d1f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
2d200 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e  alue_text16() in
2d210 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73  terface extracts
2d220 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2d230 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76  .** in the nativ
2d240 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20  e byte-order of 
2d250 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65  the host machine
2d260 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
2d270 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
2d280 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
2d290 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
2d2a0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
2d2b0 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72  tract UTF-16 str
2d2c0 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
2d2d0 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
2d2e0 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
2d2f0 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
2d300 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
2d310 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66  ic_type() interf
2d320 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
2d330 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63  apply.** numeric
2d340 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65   affinity to the
2d350 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65   value.  This me
2d360 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65  ans that an atte
2d370 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74  mpt is.** made t
2d380 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
2d390 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  lue to an intege
2d3a0 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f  r or floating po
2d3b0 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68  int.  If.** such
2d3c0 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73   a conversion is
2d3d0 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75   possible withou
2d3e0 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d  t loss of inform
2d3f0 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a  ation (in other.
2d400 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65  ** words, if the
2d410 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69   value is a stri
2d420 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69  ng that looks li
2d430 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20  ke a number).** 
2d440 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73  then the convers
2d450 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
2d460 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
2d470 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
2d480 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  s..** The [SQLIT
2d490 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
2d4a0 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76  type] after conv
2d4b0 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  ersion is return
2d4c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65  ed..**.** Please
2d4d0 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20   pay particular 
2d4e0 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65  attention to the
2d4f0 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70   fact that the p
2d500 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a  ointer returned.
2d510 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
2d520 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
2d530 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2d540 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
2d550 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2d560 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
2d570 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
2d580 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
2d590 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
2d5a0 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
2d5b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2d5c0 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
2d5d0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2d5e0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
2d5f0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
2d600 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2d610 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
2d620 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
2d630 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
2d640 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2d650 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
2d660 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2d670 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  e*] parameters..
2d680 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2d690 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 33 7d  :.**.** {H15103}
2d6a0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2d6b0 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 69 6e 74  lue_blob(V)] int
2d6c0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2d6d0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2d6e0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2d6f0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2d700 20 56 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61   V into a BLOB a
2d710 6e 64 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  nd then.**      
2d720 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 70 6f      returns a po
2d730 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e  inter to the con
2d740 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a  verted value..**
2d750 0a 2a 2a 20 7b 48 31 35 31 30 36 7d 20 54 68 65  .** {H15106} The
2d760 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d770 62 79 74 65 73 28 56 29 5d 20 69 6e 74 65 72 66  bytes(V)] interf
2d780 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ace returns the.
2d790 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
2d7a0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2d7b0 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
2d7c0 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20  g (exclusive of 
2d7d0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2d7e0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2d7f0 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74  on the string) t
2d800 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
2d810 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   by the.**      
2d820 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20      most recent 
2d830 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2d840 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20  _value_blob(V)] 
2d850 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
2d860 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2d870 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  xt(V)]..**.** {H
2d880 31 35 31 30 39 7d 20 54 68 65 20 5b 73 71 6c 69  15109} The [sqli
2d890 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
2d8a0 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  6(V)] interface 
2d8b0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20  returns the.**  
2d8c0 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f          number o
2d8d0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  f bytes in the s
2d8e0 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65  tring (exclusive
2d8f0 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
2d900 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61      zero termina
2d910 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e  tor on the strin
2d920 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75  g) that was retu
2d930 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20  rned by the.**  
2d940 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63          most rec
2d950 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2d960 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2d970 36 28 56 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  6(V)],.**       
2d980 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75     [sqlite3_valu
2d990 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d 2c 20  e_text16be(V)], 
2d9a0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
2d9b0 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d 2e 0a  e_text16le(V)]..
2d9c0 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 32 7d 20 54  **.** {H15112} T
2d9d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2d9e0 65 5f 64 6f 75 62 6c 65 28 56 29 5d 20 69 6e 74  e_double(V)] int
2d9f0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2da00 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2da10 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2da20 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2da30 20 56 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69   V into a floati
2da40 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61  ng point value a
2da50 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
2da60 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
2da70 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a   that value..**.
2da80 2a 2a 20 7b 48 31 35 31 31 35 7d 20 54 68 65 20  ** {H15115} The 
2da90 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
2daa0 6e 74 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  nt(V)] interface
2dab0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2dac0 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
2dad0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2dae0 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
2daf0 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65  o a 64-bit signe
2db00 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a  d integer and.**
2db10 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2db20 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62  s the lower 32 b
2db30 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65  its of that inte
2db40 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  ger..**.** {H151
2db50 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  18} The [sqlite3
2db60 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 56 29 5d  _value_int64(V)]
2db70 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2db80 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2db90 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2dba0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2dbb0 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34  ject V into a 64
2dbc0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2dbd0 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ger and.**      
2dbe0 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f      returns a co
2dbf0 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67  py of that integ
2dc00 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32  er..**.** {H1512
2dc10 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
2dc20 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 20 69  value_text(V)] i
2dc30 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2dc40 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2dc50 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2dc60 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2dc70 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f  ct V into a zero
2dc80 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
2dc90 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  8.**          st
2dca0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2dcb0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2dcc0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
2dcd0 20 7b 48 31 35 31 32 34 7d 20 54 68 65 20 5b 73   {H15124} The [s
2dce0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2dcf0 74 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63  t16(V)] interfac
2dd00 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
2dd10 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
2dd20 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2dd30 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
2dd40 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2dd50 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20  ated 2-byte.**  
2dd60 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20          aligned 
2dd70 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
2dd80 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20  te order.**     
2dd90 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
2dda0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2ddb0 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
2ddc0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 37 7d  ..**.** {H15127}
2ddd0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2dde0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d  lue_text16be(V)]
2ddf0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2de00 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2de10 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2de20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2de30 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65  ject V into a ze
2de40 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d  ro-terminated 2-
2de50 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  byte.**         
2de60 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20   aligned UTF-16 
2de70 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20  big-endian.**   
2de80 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
2de90 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
2dea0 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
2deb0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33  ng..**.** {H1513
2dec0 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  0} The [sqlite3_
2ded0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56  value_text16le(V
2dee0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2def0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2df00 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
2df10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2df20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
2df30 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2df40 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20  2-byte.**       
2df50 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31     aligned UTF-1
2df60 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a  6 little-endian.
2df70 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
2df80 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
2df90 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
2dfa0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
2dfb0 48 31 35 31 33 33 7d 20 54 68 65 20 5b 73 71 6c  H15133} The [sql
2dfc0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
2dfd0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  V)] interface re
2dfe0 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
2dff0 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45    one of [SQLITE
2e000 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NULL], [SQLITE_
2e010 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54  INTEGER], [SQLIT
2e020 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20  E_FLOAT],.**    
2e030 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45        [SQLITE_TE
2e040 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  XT], or [SQLITE_
2e050 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72  BLOB] as appropr
2e060 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  iate for.**     
2e070 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
2e080 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2e090 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 36  V..**.** {H15136
2e0a0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2e0b0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
2e0c0 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(V)] interface 
2e0d0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 20 20 20 20  converts.**     
2e0e0 20 20 20 20 20 74 68 65 20 5b 70 72 6f 74 65 63       the [protec
2e0f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2e100 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
2e110 20 65 69 74 68 65 72 20 61 6e 20 69 6e 74 65 67   either an integ
2e120 65 72 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  er or.**        
2e130 20 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69    a floating poi
2e140 6e 74 20 76 61 6c 75 65 20 69 66 20 69 74 20 63  nt value if it c
2e150 61 6e 20 64 6f 20 73 6f 20 77 69 74 68 6f 75 74  an do so without
2e160 20 6c 6f 73 73 20 6f 66 0a 2a 2a 20 20 20 20 20   loss of.**     
2e170 20 20 20 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e       information
2e180 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 6f 6e  , and returns on
2e190 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  e of [SQLITE_NUL
2e1a0 4c 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  L],.**          
2e1b0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
2e1c0 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  , [SQLITE_FLOAT]
2e1d0 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
2e1e0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
2e1f0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73  [SQLITE_BLOB] as
2e200 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
2e210 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2e220 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2e230 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2e240 74 20 56 20 61 66 74 65 72 20 74 68 65 20 63 6f  t V after the co
2e250 6e 76 65 72 73 69 6f 6e 20 61 74 74 65 6d 70 74  nversion attempt
2e260 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ..*/.const void 
2e270 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  *sqlite3_value_b
2e280 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  lob(sqlite3_valu
2e290 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2e2a0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c  _value_bytes(sql
2e2b0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2e2c0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2e2d0 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
2e2e0 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20  value*);.double 
2e2f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f  sqlite3_value_do
2e300 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  uble(sqlite3_val
2e310 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2e320 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69  3_value_int(sqli
2e330 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c  te3_value*);.sql
2e340 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
2e350 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73  e3_value_int64(s
2e360 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2e370 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
2e380 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  har *sqlite3_val
2e390 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  ue_text(sqlite3_
2e3a0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
2e3b0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2e3c0 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  ue_text16(sqlite
2e3d0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
2e3e0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
2e3f0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71  alue_text16le(sq
2e400 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
2e410 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2e420 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
2e430 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2e440 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
2e450 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65  alue_type(sqlite
2e460 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2e470 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
2e480 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65  eric_type(sqlite
2e490 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
2e4a0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
2e4b0 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e  in Aggregate Fun
2e4c0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 48  ction Context {H
2e4d0 31 36 32 31 30 7d 20 3c 53 32 30 32 30 30 3e 0a  16210} <S20200>.
2e4e0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d  **.** The implem
2e4f0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72  entation of aggr
2e500 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2e510 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f 75  ons use this rou
2e520 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  tine to allocate
2e530 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65 20  .** a structure 
2e540 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69  for storing thei
2e550 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  r state..**.** T
2e560 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
2e570 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
2e580 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f  ate_context() ro
2e590 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
2e5a0 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69 63 75  for a.** particu
2e5b0 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c 20 53  lar aggregate, S
2e5c0 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20  QLite allocates 
2e5d0 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79  nBytes of memory
2e5e0 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61  , zeroes out tha
2e5f0 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e 64  t.** memory, and
2e600 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2e610 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73 65 63  er to it. On sec
2e620 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2e630 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  nt calls to.** s
2e640 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2e650 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74  _context() for t
2e660 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
2e670 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78  e function index
2e680 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75  ,.** the same bu
2e690 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  ffer is returned
2e6a0 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  . The implementa
2e6b0 74 69 6f 6e 20 6f 66 20 74 68 65 20 61 67 67 72  tion of the aggr
2e6c0 65 67 61 74 65 20 63 61 6e 20 75 73 65 0a 2a 2a  egate can use.**
2e6d0 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 62 75   the returned bu
2e6e0 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61  ffer to accumula
2e6f0 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  te data..**.** S
2e700 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
2e710 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 61 6c  lly frees the al
2e720 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72 20 77  located buffer w
2e730 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
2e740 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c  e.** query concl
2e750 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
2e760 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2e770 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79  should be a copy
2e780 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
2e790 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51  te3_context | SQ
2e7a0 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65  L function conte
2e7b0 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20  xt] that is the 
2e7c0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a  first parameter.
2e7d0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
2e7e0 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
2e7f0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61  implements the a
2e800 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
2e810 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
2e820 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
2e830 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
2e840 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
2e850 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67  ch.** the aggreg
2e860 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2e870 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a   is running..**.
2e880 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2e890 2a 0a 2a 2a 20 7b 48 31 36 32 31 31 7d 20 54 68  *.** {H16211} Th
2e8a0 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69  e first invocati
2e8b0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61  on of [sqlite3_a
2e8c0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2e8d0 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20  (C,N)] for.**   
2e8e0 20 20 20 20 20 20 20 61 20 70 61 72 74 69 63 75         a particu
2e8f0 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  lar instance of 
2e900 61 6e 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  an aggregate fun
2e910 63 74 69 6f 6e 20 28 66 6f 72 20 61 20 70 61 72  ction (for a par
2e920 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20  ticular.**      
2e930 20 20 20 20 63 6f 6e 74 65 78 74 20 43 29 20 63      context C) c
2e940 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
2e950 61 6c 6c 6f 63 61 74 65 20 4e 20 62 79 74 65 73  allocate N bytes
2e960 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 20   of memory,.**  
2e970 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 68 61          zero tha
2e980 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
2e990 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74  turn a pointer t
2e9a0 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  o the allocated 
2e9b0 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  memory..**.** {H
2e9c0 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65 6d 6f  16213} If a memo
2e9d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
2e9e0 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
2e9f0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
2ea00 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2ea10 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74  _context(C,N)] t
2ea20 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
2ea30 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a   returns 0..**.*
2ea40 2a 20 7b 48 31 36 32 31 35 7d 20 53 65 63 6f 6e  * {H16215} Secon
2ea50 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
2ea60 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 0a   invocations of.
2ea70 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2ea80 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2ea90 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72  ontext(C,N)] for
2eaa0 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74 65 78   the same contex
2eab0 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a 20 20  t pointer C.**  
2eac0 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65 20 74          ignore t
2ead0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 61  he N parameter a
2eae0 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e  nd return a poin
2eaf0 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d 65 0a  ter to the same.
2eb00 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c 6f 63  **          bloc
2eb10 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 74 75  k of memory retu
2eb20 72 6e 65 64 20 62 79 20 74 68 65 20 66 69 72 73  rned by the firs
2eb30 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  t invocation..**
2eb40 0a 2a 2a 20 7b 48 31 36 32 31 37 7d 20 54 68 65  .** {H16217} The
2eb50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
2eb60 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 61 67  d by [sqlite3_ag
2eb70 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2eb80 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20  C,N)] is.**     
2eb90 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c       automatical
2eba0 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68 65 20  ly freed on the 
2ebb0 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  next call to [sq
2ebc0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
2ebd0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
2ebe0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2ebf0 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  )] for the [prep
2ec00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ec10 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20  containing.**   
2ec20 20 20 20 20 20 20 20 74 68 65 20 61 67 67 72 65         the aggre
2ec30 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 61 73  gate function as
2ec40 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 63 6f  sociated with co
2ec50 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64  ntext C..*/.void
2ec60 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
2ec70 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
2ec80 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2ec90 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
2eca0 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
2ecb0 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
2ecc0 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c 53 32  ons {H16240} <S2
2ecd0 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0200>.**.** The 
2ece0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2ecf0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
2ed00 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
2ed10 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
2ed20 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
2ed30 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
2ed40 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
2ed50 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
2ed60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2ed70 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
2ed80 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2ed90 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
2eda0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
2edb0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
2edc0 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
2edd0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
2ede0 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a  nction. {END}.**
2edf0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
2ee00 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2ee10 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
2ee20 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
2ee30 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2ee40 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2ee50 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  n is running..**
2ee60 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2ee70 2a 2a 0a 2a 2a 20 7b 48 31 36 32 34 33 7d 20 54  **.** {H16243} T
2ee80 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  he [sqlite3_user
2ee90 5f 64 61 74 61 28 43 29 5d 20 69 6e 74 65 72 66  _data(C)] interf
2eea0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
2eeb0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  py of the.**    
2eec0 20 20 20 20 20 20 50 20 70 6f 69 6e 74 65 72 20        P pointer 
2eed0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
2eee0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2eef0 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  n(D,X,N,E,P,F,S,
2ef00 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  L)].**          
2ef10 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  or [sqlite3_crea
2ef20 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c  te_function16(D,
2ef30 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20  X,N,E,P,F,S,L)] 
2ef40 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20  call that.**    
2ef50 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64        registered
2ef60 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2ef70 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  n associated wit
2ef80 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  h [sqlite3_conte
2ef90 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  xt] C..*/.void *
2efa0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2efb0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
2efc0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2efd0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
2efe0 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
2eff0 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d  nctions {H16250}
2f000 20 3c 53 36 30 36 30 30 3e 3c 53 32 30 32 30 30   <S60600><S20200
2f010 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
2f020 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2f030 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
2f040 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
2f050 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
2f060 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
2f070 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2f080 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
2f090 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
2f0a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f0b0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
2f0c0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2f0d0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
2f0e0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
2f0f0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
2f100 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
2f110 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
2f120 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e  nction..**.** IN
2f130 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2f140 7b 48 31 36 32 35 33 7d 20 54 68 65 20 5b 73 71  {H16253} The [sq
2f150 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2f160 5f 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e 74 65  _handle(C)] inte
2f170 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2f180 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20  copy of the.**  
2f190 20 20 20 20 20 20 20 20 44 20 70 6f 69 6e 74 65          D pointe
2f1a0 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  r from the [sqli
2f1b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f1c0 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  ion(D,X,N,E,P,F,
2f1d0 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,L)].**        
2f1e0 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72    or [sqlite3_cr
2f1f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2f200 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
2f210 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20  ] call that.**  
2f220 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
2f230 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ed the SQL funct
2f240 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77  ion associated w
2f250 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ith [sqlite3_con
2f260 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c 69  text] C..*/.sqli
2f270 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e  te3 *sqlite3_con
2f280 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73  text_db_handle(s
2f290 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2f2a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f2b0 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
2f2c0 6c 69 61 72 79 20 44 61 74 61 20 7b 48 31 36 32  liary Data {H162
2f2d0 37 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  70} <S20200>.**.
2f2e0 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
2f2f0 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d   two functions m
2f300 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63  ay be used by sc
2f310 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
2f320 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
2f330 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68  te metadata with
2f340 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
2f350 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
2f360 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
2f370 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
2f380 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
2f390 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
2f3a0 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
2f3b0 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
2f3c0 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
2f3d0 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
2f3e0 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61  ated metadata ma
2f3f0 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
2f400 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75  This may.** be u
2f410 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
2f420 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c  , to add a regul
2f430 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
2f440 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a  tching scalar.**
2f450 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
2f460 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
2f470 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
2f480 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f  xpression is sto
2f490 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
2f4a0 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
2f4b0 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
2f4c0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
2f4d0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
2f4e0 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
2f4f0 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
2f500 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
2f510 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
2f520 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
2f530 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
2f540 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
2f550 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
2f560 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
2f570 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
2f580 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
2f590 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
2f5a0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
2f5b0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
2f5c0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
2f5d0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2f5e0 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
2f5f0 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
2f600 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
2f610 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
2f620 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
2f630 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
2f640 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
2f650 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2f660 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f   function. If no
2f670 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65   metadata has be
2f680 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20  en ever.** been 
2f690 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20  set for the Nth 
2f6a0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
2f6b0 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20  function, or if 
2f6c0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2f6d0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61  g.** function pa
2f6e0 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e  rameter has chan
2f6f0 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65  ged since the me
2f700 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c  ta-data was set,
2f710 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
2f720 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72  _get_auxdata() r
2f730 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
2f740 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
2f750 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
2f760 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
2f770 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64   saves the metad
2f780 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ata.** pointed t
2f790 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72  o by its 3rd par
2f7a0 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65  ameter as the me
2f7b0 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
2f7c0 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
2f7d0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2f7e0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2f7f0 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ion.  Subsequent
2f800 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
2f810 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2f820 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  () might return 
2f830 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74  this data, if it
2f840 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e   has.** not been
2f850 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49   destroyed..** I
2f860 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  f it is not NULL
2f870 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  , SQLite will in
2f880 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
2f890 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  tor.** function 
2f8a0 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68  given by the 4th
2f8b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2f8c0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2f8d0 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65  a() on.** the me
2f8e0 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20  tadata when the 
2f8f0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  corresponding fu
2f900 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
2f910 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77   changes.** or w
2f920 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
2f930 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c  ement completes,
2f940 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
2f950 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51   first..**.** SQ
2f960 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20  Lite is free to 
2f970 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63  call the destruc
2f980 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74  tor and drop met
2f990 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20  adata on any.** 
2f9a0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79  parameter of any
2f9b0 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79   function at any
2f9c0 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79   time.  The only
2f9d0 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68   guarantee is th
2f9e0 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75  at.** the destru
2f9f0 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c  ctor will be cal
2fa00 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d  led before the m
2fa10 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70  etadata is dropp
2fa20 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61  ed..**.** In pra
2fa30 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20  ctice, metadata 
2fa40 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74  is preserved bet
2fa50 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61  ween function ca
2fa60 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65  lls for.** expre
2fa70 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ssions that are 
2fa80 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70  constant at comp
2fa90 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69  ile time. This i
2faa0 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a  ncludes literal.
2fab0 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51  ** values and SQ
2fac0 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a  L variables..**.
2fad0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2fae0 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
2faf0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
2fb00 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
2fb10 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
2fb20 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
2fb30 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2fb40 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 32 7d 20  .**.** {H16272} 
2fb50 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  The [sqlite3_get
2fb60 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d 20 69  _auxdata(C,N)] i
2fb70 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2fb80 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
2fb90 20 20 20 20 20 20 20 74 6f 20 6d 65 74 61 64 61         to metada
2fba0 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
2fbb0 74 68 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d  th the Nth param
2fbc0 65 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20  eter of the SQL 
2fbd0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  function.**     
2fbe0 20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e 74 65       whose conte
2fbf0 78 74 20 69 73 20 43 2c 20 6f 72 20 4e 55 4c 4c  xt is C, or NULL
2fc00 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   if there is no 
2fc10 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
2fc20 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
2fc30 77 69 74 68 20 74 68 61 74 20 70 61 72 61 6d 65  with that parame
2fc40 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  ter..**.** {H162
2fc50 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  74} The [sqlite3
2fc60 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
2fc70 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,P,D)] interface
2fc80 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74 61 64   assigns a metad
2fc90 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ata.**          
2fca0 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74 68 65  pointer P to the
2fcb0 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   Nth parameter o
2fcc0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
2fcd0 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 78 74 20  on with context 
2fce0 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 36  C..**.** {H16276
2fcf0 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  } SQLite will in
2fd00 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
2fd10 74 6f 72 20 44 20 77 69 74 68 20 61 20 73 69 6e  tor D with a sin
2fd20 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  gle argument.** 
2fd30 20 20 20 20 20 20 20 20 20 77 68 69 63 68 20 69           which i
2fd40 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 70  s the metadata p
2fd50 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69  ointer P followi
2fd60 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  ng a call to.** 
2fd70 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2fd80 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
2fd90 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c  N,P,D)] when SQL
2fda0 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f  ite ceases to ho
2fdb0 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ld.**          t
2fdc0 68 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a  he metadata..**.
2fdd0 2a 2a 20 7b 48 31 36 32 37 37 7d 20 53 51 4c 69  ** {H16277} SQLi
2fde0 74 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c  te ceases to hol
2fdf0 64 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 61  d metadata for a
2fe00 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70  n SQL function p
2fe10 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
2fe20 20 20 20 20 20 77 68 65 6e 20 74 68 65 20 76 61       when the va
2fe30 6c 75 65 20 6f 66 20 74 68 61 74 20 70 61 72 61  lue of that para
2fe40 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a  meter changes..*
2fe50 2a 0a 2a 2a 20 7b 48 31 36 32 37 38 7d 20 57 68  *.** {H16278} Wh
2fe60 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  en [sqlite3_set_
2fe70 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29  auxdata(C,N,P,D)
2fe80 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68  ] is invoked, th
2fe90 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
2fea0 20 20 20 20 20 20 20 20 20 69 73 20 63 61 6c 6c           is call
2feb0 65 64 20 66 6f 72 20 61 6e 79 20 70 72 69 6f 72  ed for any prior
2fec0 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
2fed0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73 61  ated with the sa
2fee0 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20  me function.**  
2fef0 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20          context 
2ff00 43 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20  C and parameter 
2ff10 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 39  N..**.** {H16279
2ff20 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 61  } SQLite will ca
2ff30 6c 6c 20 64 65 73 74 72 75 63 74 6f 72 73 20 66  ll destructors f
2ff40 6f 72 20 61 6e 79 20 6d 65 74 61 64 61 74 61 20  or any metadata 
2ff50 69 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a  it is holding.**
2ff60 20 20 20 20 20 20 20 20 20 20 69 6e 20 61 20 70            in a p
2ff70 61 72 74 69 63 75 6c 61 72 20 5b 70 72 65 70 61  articular [prepa
2ff80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2ff90 20 77 68 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20   when either.** 
2ffa0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2ffb0 33 5f 72 65 73 65 74 28 53 29 5d 20 6f 72 20 5b  3_reset(S)] or [
2ffc0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2ffd0 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a  (S)] is called..
2ffe0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
2fff0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _get_auxdata(sql
30000 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
30010 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt N);.void sqli
30020 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
30030 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30040 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20  , int N, void*, 
30050 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29  void (*)(void*))
30060 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
30070 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65  EF: Constants De
30080 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44  fining Special D
30090 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69  estructor Behavi
300a0 6f 72 20 7b 48 31 30 32 38 30 7d 20 3c 53 33 30  or {H10280} <S30
300b0 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  100>.**.** These
300c0 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c   are special val
300d0 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74  ues for the dest
300e0 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70  ructor that is p
300f0 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
30100 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e  ** final argumen
30110 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  t to routines li
30120 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ke [sqlite3_resu
30130 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20  lt_blob()].  If 
30140 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
30150 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51  * argument is SQ
30160 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20  LITE_STATIC, it 
30170 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
30180 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69  ontent pointer i
30190 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e  s constant.** an
301a0 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61  d will never cha
301b0 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f  nge.  It does no
301c0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73  t need to be des
301d0 74 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a 2a 20  troyed.  The.** 
301e0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
301f0 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61   value means tha
30200 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69  t the content wi
30210 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65  ll likely change
30220 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20   in.** the near 
30230 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20  future and that 
30240 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61  SQLite should ma
30250 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ke its own priva
30260 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68  te copy of.** th
30270 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65  e content before
30280 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
30290 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73  * The typedef is
302a0 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f   necessary to wo
302b0 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65  rk around proble
302c0 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a  ms in certain.**
302d0 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20   C++ compilers. 
302e0 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39   See ticket #219
302f0 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f  1..*/.typedef vo
30300 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73  id (*sqlite3_des
30310 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f  tructor_type)(vo
30320 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  id*);.#define SQ
30330 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20  LITE_STATIC     
30340 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
30350 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64  uctor_type)0).#d
30360 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
30370 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74  NSIENT   ((sqlit
30380 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
30390 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  pe)-1)../*.** CA
303a0 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20  PI3REF: Setting 
303b0 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e  The Result Of An
303c0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 48   SQL Function {H
303d0 31 36 34 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a  16400} <S20200>.
303e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
303f0 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79  ines are used by
30400 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46   the xFunc or xF
30410 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74  inal callbacks t
30420 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  hat.** implement
30430 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
30440 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  nd aggregates.  
30450 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  See.** [sqlite3_
30460 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
30470 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
30480 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
30490 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69  6()].** for addi
304a0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
304b0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on..**.** These 
304c0 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76  functions work v
304d0 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68  ery much like th
304e0 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  e [parameter bin
304f0 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  ding] family of.
30500 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  ** functions use
30510 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73  d to bind values
30520 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
30530 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20  ers in prepared 
30540 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52  statements..** R
30550 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c  efer to the [SQL
30560 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75   parameter] docu
30570 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
30580 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
30590 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
305a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
305b0 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20  lob() interface 
305c0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
305d0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
305e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
305f0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
30600 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e  e BLOB whose con
30610 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a  tent is pointed.
30620 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ** to by the sec
30630 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  ond parameter an
30640 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74  d which is N byt
30650 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20  es long where N 
30660 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20  is the.** third 
30670 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
30680 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
30690 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69  ult_zeroblob() i
306a0 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68  nterfaces set th
306b0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
306c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
306d0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
306e0 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e  to be a BLOB con
306f0 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
30700 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20  .** bytes and N 
30710 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77  bytes in size, w
30720 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61  here N is the va
30730 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70  lue of the 2nd p
30740 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
30750 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
30760 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65  lt_double() inte
30770 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
30780 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
30790 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
307a0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
307b0 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70   be a floating p
307c0 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69  oint value speci
307d0 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32  fied.** by its 2
307e0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
307f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
30800 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
30810 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
30820 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74  _error16() funct
30830 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68  ions.** cause th
30840 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51  e implemented SQ
30850 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68  L function to th
30860 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  row an exception
30870 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  ..** SQLite uses
30880 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
30890 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
308a0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
308b0 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
308c0 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
308d0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
308e0 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
308f0 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
30900 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69 74 65  message.  SQLite
30910 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
30920 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
30930 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
30940 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
30950 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 53 51  r() as UTF-8. SQ
30960 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
30970 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
30980 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
30990 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
309a0 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  TF-16 in native.
309b0 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
309c0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
309d0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
309e0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
309f0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
30a00 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
30a10 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
30a20 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
30a30 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
30a40 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
30a50 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
30a60 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
30a70 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 68  er..** If the th
30a80 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
30a90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30aa0 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
30ab0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30ac0 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
30ad0 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
30ae0 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
30af0 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
30b00 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
30b10 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
30b20 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
30b30 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65   message..** The
30b40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30b50 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
30b60 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30b70 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  16().** routines
30b80 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20   make a private 
30b90 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f  copy of the erro
30ba0 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62  r message text b
30bb0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65  efore.** they re
30bc0 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68  turn.  Hence, th
30bd0 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
30be0 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74  on can deallocat
30bf0 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74  e or.** modify t
30c00 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68  he text after th
30c10 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75  ey return withou
30c20 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73  t harm..** The s
30c30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
30c40 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
30c50 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
30c60 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
30c70 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
30c80 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
30c90 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
30ca0 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 66 61  nction.  By defa
30cb0 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f  ult,.** the erro
30cc0 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45  r code is SQLITE
30cd0 5f 45 52 52 4f 52 2e 20 20 41 20 73 75 62 73 65  _ERROR.  A subse
30ce0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
30cf0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30d00 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
30d10 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
30d20 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
30d30 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
30d40 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
30d50 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
30d60 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74  ult_toobig() int
30d70 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
30d80 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
30d90 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
30da0 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69  ting that a stri
30db0 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f  ng or BLOB is to
30dc0 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65   long to represe
30dd0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  nt..**.** The sq
30de0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d  lite3_result_nom
30df0 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  em() interface c
30e00 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
30e10 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a  throw an error.*
30e20 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  * indicating tha
30e30 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  t a memory alloc
30e40 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a  ation failed..**
30e50 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
30e60 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74  result_int() int
30e70 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
30e80 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
30e90 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
30ea0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
30eb0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32  ion to be the 32
30ec0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
30ed0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
30ee0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
30ef0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73  gument..** The s
30f00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
30f10 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
30f20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
30f30 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
30f40 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
30f50 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
30f60 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69  be the 64-bit si
30f70 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
30f80 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
30f90 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
30fa0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
30fb0 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29  e3_result_null()
30fc0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
30fd0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
30fe0 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
30ff0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
31000 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55  unction to be NU
31010 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  LL..**.** The sq
31020 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31030 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73  t(), sqlite3_res
31040 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  ult_text16(),.**
31050 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31060 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20  text16le(), and 
31070 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31080 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66  ext16be() interf
31090 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20  aces.** set the 
310a0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
310b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
310c0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
310d0 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74   to be.** a text
310e0 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
310f0 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20   represented as 
31100 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61  UTF-8, UTF-16 na
31110 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c  tive byte order,
31120 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
31130 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e endian, or UTF
31140 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20  -16 big endian, 
31150 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
31160 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68   SQLite takes th
31170 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
31180 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
31190 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
311a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
311b0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
311c0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
311d0 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33  ces..** If the 3
311e0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
311f0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
31200 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
31210 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
31220 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
31230 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
31240 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
31250 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
31260 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
31270 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
31280 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
31290 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
312a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
312b0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
312c0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
312d0 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79   then as many by
312e0 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
312f0 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74  ers) of the text
31300 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
31310 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
31320 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73  ter are taken as
31330 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
31340 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63  -defined.** func
31350 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  tion result..** 
31360 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
31370 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
31380 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
31390 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
313a0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
313b0 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e  _blob is a non-N
313c0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
313d0 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74  n SQLite calls t
313e0 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  hat.** function 
313f0 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  as the destructo
31400 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72  r on the text or
31410 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65   BLOB result whe
31420 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
31430 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
31440 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68  result..** If th
31450 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
31460 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
31470 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
31480 72 66 61 63 65 73 20 6f 72 0a 2a 2a 20 73 71 6c  rfaces or.** sql
31490 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
314a0 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
314b0 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
314c0 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c  STATIC, then SQL
314d0 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74  ite.** assumes t
314e0 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20  hat the text or 
314f0 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69  BLOB result is i
31500 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65  n constant space
31510 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a   and does not.**
31520 20 63 6f 70 79 20 74 68 65 20 69 74 20 6f 72 20   copy the it or 
31530 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f  call a destructo
31540 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  r when it has fi
31550 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
31560 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20  t result..** If 
31570 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
31580 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
31590 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
315a0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
315b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
315c0 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
315d0 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
315e0 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74  E_TRANSIENT.** t
315f0 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  hen SQLite makes
31600 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72   a copy of the r
31610 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65  esult into space
31620 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a   obtained from.*
31630 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
31640 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65  malloc()] before
31650 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
31660 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
31670 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
31680 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
31690 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
316a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
316b0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
316c0 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a  o be a copy the.
316d0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
316e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
316f0 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20  bject specified 
31700 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
31710 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71  eter.  The.** sq
31720 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
31730 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
31740 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
31750 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
31760 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
31770 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
31780 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
31790 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
317a0 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
317b0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
317c0 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
317d0 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
317e0 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
317f0 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20  ** A [protected 
31800 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
31810 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73  bject may always
31820 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61   be used where a
31830 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
31840 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
31850 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69   object is requi
31860 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a  red, so either.*
31870 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74  * kind of [sqlit
31880 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
31890 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74   can be used wit
318a0 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  h this interface
318b0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65  ..**.** If these
318c0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
318d0 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e  lled from within
318e0 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74   the different t
318f0 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68  hread.** than th
31900 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67  e one containing
31910 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
31920 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
31930 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a  n that received.
31940 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
31950 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72  context] pointer
31960 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
31970 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
31980 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
31990 2a 0a 2a 2a 20 7b 48 31 36 34 30 33 7d 20 54 68  *.** {H16403} Th
319a0 65 20 64 65 66 61 75 6c 74 20 72 65 74 75 72 6e  e default return
319b0 20 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20   value from any 
319c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
319d0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  NULL..**.** {H16
319e0 34 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  406} The [sqlite
319f0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c  3_result_blob(C,
31a00 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  V,N,D)] interfac
31a10 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
31a20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
31a30 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
31a40 6f 6e 20 43 20 74 6f 20 62 65 20 61 20 42 4c 4f  on C to be a BLO
31a50 42 20 74 68 61 74 20 69 73 20 4e 20 62 79 74 65  B that is N byte
31a60 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  s.**          in
31a70 20 6c 65 6e 67 74 68 20 61 6e 64 20 77 69 74 68   length and with
31a80 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 64   content pointed
31a90 20 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20   to by V..**.** 
31aa0 7b 48 31 36 34 30 39 7d 20 54 68 65 20 5b 73 71  {H16409} The [sq
31ab0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
31ac0 62 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66  ble(C,V)] interf
31ad0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
31ae0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
31af0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
31b00 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
31b10 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
31b20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  value V..**.** {
31b30 48 31 36 34 31 32 7d 20 54 68 65 20 5b 73 71 6c  H16412} The [sql
31b40 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31b50 72 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66  r(C,V,N)] interf
31b60 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ace changes the 
31b70 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
31b80 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63     value of func
31b90 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
31ba0 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65  exception with e
31bb0 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20  rror code.**    
31bc0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52        [SQLITE_ER
31bd0 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 2d 38  ROR] and a UTF-8
31be0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 63   error message c
31bf0 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20  opied from V up 
31c00 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
31c10 20 20 20 66 69 72 73 74 20 7a 65 72 6f 20 62 79     first zero by
31c20 74 65 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79  te or until N by
31c30 74 65 73 20 61 72 65 20 72 65 61 64 20 69 66 20  tes are read if 
31c40 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a  N is positive..*
31c50 2a 0a 2a 2a 20 7b 48 31 36 34 31 35 7d 20 54 68  *.** {H16415} Th
31c60 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
31c70 74 5f 65 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29  t_error16(C,V,N)
31c80 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
31c90 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
31ca0 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
31cb0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
31cc0 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
31cd0 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
31ce0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  e.**          [S
31cf0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64  QLITE_ERROR] and
31d00 20 61 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65   a UTF-16 native
31d10 20 62 79 74 65 20 6f 72 64 65 72 20 65 72 72 6f   byte order erro
31d20 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20  r message.**    
31d30 20 20 20 20 20 20 63 6f 70 69 65 64 20 66 72 6f        copied fro
31d40 6d 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69  m V up to the fi
31d50 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
31d60 74 6f 72 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62  tor or until N b
31d70 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ytes.**         
31d80 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 20 69   are read if N i
31d90 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a  s positive..**.*
31da0 2a 20 7b 48 31 36 34 31 38 7d 20 54 68 65 20 5b  * {H16418} The [
31db0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31dc0 72 72 6f 72 5f 74 6f 6f 62 69 67 28 43 29 5d 20  rror_toobig(C)] 
31dd0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
31de0 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20  s the return.** 
31df0 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
31e00 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43  f the function C
31e10 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74   to be an except
31e20 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63  ion with error c
31e30 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
31e40 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20  [SQLITE_TOOBIG] 
31e50 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61  and an appropria
31e60 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  te error message
31e70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 31 7d  ..**.** {H16421}
31e80 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
31e90 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
31ea0 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (C)] interface c
31eb0 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72  hanges the retur
31ec0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  n.**          va
31ed0 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  lue of the funct
31ee0 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65  ion C to be an e
31ef0 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72  xception with er
31f00 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20  ror code.**     
31f10 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d       [SQLITE_NOM
31f20 45 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f  EM] and an appro
31f30 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
31f40 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  sage..**.** {H16
31f50 34 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  424} The [sqlite
31f60 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
31f70 6f 64 65 28 43 2c 45 29 5d 20 69 6e 74 65 72 66  ode(C,E)] interf
31f80 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ace changes the 
31f90 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
31fa0 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20     value of the 
31fb0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
31fc0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69   an exception wi
31fd0 74 68 20 65 72 72 6f 72 20 63 6f 64 65 20 45 2e  th error code E.
31fe0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 54 68 65  .**          The
31ff0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
32000 65 78 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  ext is unchanged
32010 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 37 7d  ..**.** {H16427}
32020 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
32030 73 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69  sult_int(C,V)] i
32040 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
32050 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
32060 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
32070 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
32080 65 20 74 68 65 20 33 32 2d 62 69 74 20 69 6e 74  e the 32-bit int
32090 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a  eger value V..**
320a0 0a 2a 2a 20 7b 48 31 36 34 33 30 7d 20 54 68 65  .** {H16430} The
320b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
320c0 5f 69 6e 74 36 34 28 43 2c 56 29 5d 20 69 6e 74  _int64(C,V)] int
320d0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
320e0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
320f0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
32100 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
32110 74 68 65 20 36 34 2d 62 69 74 20 69 6e 74 65 67  the 64-bit integ
32120 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a  er value V..**.*
32130 2a 20 7b 48 31 36 34 33 33 7d 20 54 68 65 20 5b  * {H16433} The [
32140 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
32150 75 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66 61 63  ull(C)] interfac
32160 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
32170 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
32180 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
32190 6f 6e 20 43 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  on C to be NULL.
321a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 36 7d 20  .**.** {H16436} 
321b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
321c0 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44  ult_text(C,V,N,D
321d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
321e0 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
321f0 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
32200 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
32210 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d 38 20  to be the UTF-8 
32220 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  string.**       
32230 20 20 20 56 20 75 70 20 74 6f 20 74 68 65 20 66     V up to the f
32240 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69  irst zero if N i
32250 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20  s negative.**   
32260 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69         or the fi
32270 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56  rst N bytes of V
32280 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67   if N is non-neg
32290 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ative..**.** {H1
322a0 36 34 33 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  6439} The [sqlit
322b0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
322c0 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
322d0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
322e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
322f0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
32300 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
32310 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  e UTF-16 native 
32320 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
32330 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20         string V 
32340 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
32350 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67  zero if N is neg
32360 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  ative.**        
32370 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e    or the first N
32380 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e   bytes of V if N
32390 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
323a0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 32 7d  ..**.** {H16442}
323b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
323c0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c  sult_text16be(C,
323d0 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  V,N,D)] interfac
323e0 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
323f0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
32400 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
32410 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55  on C to be the U
32420 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e  TF-16 big-endian
32430 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
32440 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20  ing V up to the 
32450 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20  first zero if N 
32460 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20  is negative.**  
32470 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66          or the f
32480 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 72 20  irst N bytes or 
32490 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  V if N is non-ne
324a0 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  gative..**.** {H
324b0 31 36 34 34 35 7d 20 54 68 65 20 5b 73 71 6c 69  16445} The [sqli
324c0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
324d0 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  6le(C,V,N,D)] in
324e0 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
324f0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
32500 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
32510 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
32520 20 74 68 65 20 55 54 46 2d 31 36 20 6c 69 74 74   the UTF-16 litt
32530 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20  le-endian.**    
32540 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75        string V u
32550 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
32560 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61  ero if N is nega
32570 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  tive.**         
32580 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20   or the first N 
32590 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20  bytes of V if N 
325a0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e  is non-negative.
325b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 38 7d 20  .**.** {H16448} 
325c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
325d0 75 6c 74 5f 76 61 6c 75 65 28 43 2c 56 29 5d 20  ult_value(C,V)] 
325e0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
325f0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
32600 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
32610 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
32620 62 65 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  be the [unprotec
32630 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
32640 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  e].**          o
32650 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  bject V..**.** {
32660 48 31 36 34 35 31 7d 20 54 68 65 20 5b 73 71 6c  H16451} The [sql
32670 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
32680 62 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74 65 72  blob(C,N)] inter
32690 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
326a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
326b0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
326c0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
326d0 20 4e 2d 62 79 74 65 20 42 4c 4f 42 20 6f 66 20   N-byte BLOB of 
326e0 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a  all zeros..**.**
326f0 20 7b 48 31 36 34 35 34 7d 20 54 68 65 20 5b 73   {H16454} The [s
32700 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32710 72 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ror()] and [sqli
32720 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
32730 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  16()].**        
32740 20 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b    interfaces mak
32750 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 69  e a copy of thei
32760 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  r error message 
32770 73 74 72 69 6e 67 73 20 62 65 66 6f 72 65 0a 2a  strings before.*
32780 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
32790 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ning..**.** {H16
327a0 34 35 37 7d 20 49 66 20 74 68 65 20 44 20 64 65  457} If the D de
327b0 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74  structor paramet
327c0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  er to [sqlite3_r
327d0 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
327e0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
327f0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
32800 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
32810 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  , [sqlite3_resul
32820 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
32830 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
32840 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32850 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
32860 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
32870 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
32880 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
32890 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e  N,D)] is the con
328a0 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54  stant [SQLITE_ST
328b0 41 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ATIC].**        
328c0 20 20 74 68 65 6e 20 6e 6f 20 64 65 73 74 72 75    then no destru
328d0 63 74 6f 72 20 69 73 20 65 76 65 72 20 63 61 6c  ctor is ever cal
328e0 6c 65 64 20 6f 6e 20 74 68 65 20 70 6f 69 6e 74  led on the point
328f0 65 72 20 56 20 61 6e 64 20 53 51 4c 69 74 65 0a  er V and SQLite.
32900 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 75  **          assu
32910 6d 65 73 20 74 68 61 74 20 56 20 69 73 20 69 6d  mes that V is im
32920 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b  mutable..**.** {
32930 48 31 36 34 36 30 7d 20 49 66 20 74 68 65 20 44  H16460} If the D
32940 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61   destructor para
32950 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
32960 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c  3_result_blob(C,
32970 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
32980 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
32990 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c  sult_text(C,V,N,
329a0 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  D)], [sqlite3_re
329b0 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c  sult_text16(C,V,
329c0 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
329d0 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
329e0 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c  lt_text16be(C,V,
329f0 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  N,D)], or.**    
32a00 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
32a10 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43  esult_text16le(C
32a20 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20  ,V,N,D)] is the 
32a30 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20 20 20  constant.**     
32a40 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 52 41       [SQLITE_TRA
32a50 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 74 68 65  NSIENT] then the
32a60 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65   interfaces make
32a70 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
32a80 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  **          cont
32a90 65 6e 74 20 6f 66 20 56 20 61 6e 64 20 72 65 74  ent of V and ret
32aa0 61 69 6e 73 20 74 68 65 20 63 6f 70 79 2e 0a 2a  ains the copy..*
32ab0 2a 0a 2a 2a 20 7b 48 31 36 34 36 33 7d 20 49 66  *.** {H16463} If
32ac0 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f   the D destructo
32ad0 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  r parameter to [
32ae0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
32af0 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  lob(C,V,N,D)],.*
32b00 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
32b10 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
32b20 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69  C,V,N,D)], [sqli
32b30 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
32b40 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  6(C,V,N,D)],.** 
32b50 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
32b60 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
32b70 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a  e(C,V,N,D)], or.
32b80 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
32b90 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32ba0 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  16le(C,V,N,D)] i
32bb0 73 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f 74 68  s some value oth
32bc0 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  er than.**      
32bd0 20 20 20 20 74 68 65 20 63 6f 6e 73 74 61 6e 74      the constant
32be0 73 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  s [SQLITE_STATIC
32bf0 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 54 52  ] and [SQLITE_TR
32c00 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 0a 2a 2a  ANSIENT] then.**
32c10 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65            SQLite
32c20 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
32c30 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69   destructor D wi
32c40 74 68 20 56 20 61 73 20 69 74 73 20 6f 6e 6c 79  th V as its only
32c50 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20   argument.**    
32c60 20 20 20 20 20 20 77 68 65 6e 20 69 74 20 68 61        when it ha
32c70 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
32c80 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a  the V value..*/.
32c90 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32ca0 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
32cb0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
32cc0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
32cd0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
32ce0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
32cf0 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
32d00 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
32d10 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
32d20 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
32d30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32d40 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
32d50 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
32d60 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
32d70 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32d80 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
32d90 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
32da0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
32db0 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
32dc0 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
32dd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32de0 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
32df0 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
32e00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32e10 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
32e20 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
32e30 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
32e40 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
32e50 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
32e60 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
32e70 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
32e80 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
32e90 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
32ea0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
32eb0 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
32ec0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
32ed0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32ee0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
32ef0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
32f00 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
32f10 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
32f20 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32f30 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
32f40 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
32f50 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
32f60 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
32f70 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32f80 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
32f90 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
32fa0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
32fb0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
32fc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32fd0 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
32fe0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
32ff0 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
33000 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
33010 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
33020 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
33030 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
33040 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
33050 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
33060 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
33070 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
33080 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
33090 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
330a0 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20 7b 48  ing Sequences {H
330b0 31 36 36 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a  16600} <S20300>.
330c0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
330d0 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74  tions are used t
330e0 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74  o add new collat
330f0 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f  ion sequences to
33100 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
33110 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
33120 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
33130 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
33140 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
33150 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69   the new collati
33160 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73  on sequence is s
33170 70 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54  pecified as a UT
33180 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f  F-8 string.** fo
33190 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
331a0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64  _collation() and
331b0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
331c0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a  collation_v2().*
331d0 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73  * and a UTF-16 s
331e0 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65  tring for sqlite
331f0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33200 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63  on16(). In all c
33210 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  ases.** the name
33220 20 69 73 20 70 61 73 73 65 64 20 61 73 20 74 68   is passed as th
33230 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
33240 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
33250 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75  * The third argu
33260 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20  ment may be one 
33270 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73  of the constants
33280 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a   [SQLITE_UTF8],.
33290 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ** [SQLITE_UTF16
332a0 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  LE] or [SQLITE_U
332b0 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74  TF16BE], indicat
332c0 69 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65  ing that the use
332d0 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f  r-supplied.** ro
332e0 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f  utine expects to
332f0 20 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74   be passed point
33300 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65  ers to strings e
33310 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
33320 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  -8,.** UTF-16 li
33330 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle-endian, or 
33340 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61  UTF-16 big-endia
33350 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
33360 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72   The.** third ar
33370 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73  gument might als
33380 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  o be [SQLITE_UTF
33390 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69  16_ALIGNED] to i
333a0 6e 64 69 63 61 74 65 20 74 68 61 74 0a 2a 2a 20  ndicate that.** 
333b0 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65  the routine expe
333c0 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  cts pointers to 
333d0 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67  16-bit word alig
333e0 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f  ned strings.** o
333f0 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  f UTF-16 in the 
33400 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
33410 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 63 6f  r of the host co
33420 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20  mputer..**.** A 
33430 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75  pointer to the u
33440 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75  ser supplied rou
33450 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73  tine must be pas
33460 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68  sed as the fifth
33470 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49  .** argument.  I
33480 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  f it is NULL, th
33490 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  is is the same a
334a0 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  s deleting the c
334b0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
334c0 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51  ence (so that SQ
334d0 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c  Lite cannot call
334e0 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a   it anymore)..**
334f0 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61   Each time the a
33500 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c  pplication suppl
33510 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ied function is 
33520 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70  invoked, it is p
33530 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20  assed.** as its 
33540 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
33550 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
33560 69 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  id* passed as th
33570 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
33580 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
33590 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
335a0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
335b0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
335c0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65  ()..**.** The re
335d0 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74  maining argument
335e0 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  s to the applica
335f0 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f  tion-supplied ro
33600 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74  utine are two st
33610 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72  rings,.** each r
33620 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20  epresented by a 
33630 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70  (length, data) p
33640 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20  air and encoded 
33650 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a  in the encoding.
33660 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73  ** that was pass
33670 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
33680 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68  argument when th
33690 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  e collation sequ
336a0 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69  ence was.** regi
336b0 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54  stered. {END}  T
336c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
336d0 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
336e0 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a   routine should.
336f0 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69  ** return negati
33700 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69  ve, zero or posi
33710 74 69 76 65 20 69 66 20 74 68 65 20 66 69 72 73  tive if the firs
33720 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
33730 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20   than,.** equal 
33740 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74  to, or greater t
33750 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 73  han the second s
33760 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52  tring. i.e. (STR
33770 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e  ING1 - STRING2).
33780 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
33790 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
337a0 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c  ion_v2() works l
337b0 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  ike sqlite3_crea
337c0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a  te_collation().*
337d0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
337e0 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20   takes an extra 
337f0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
33800 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66  s a destructor f
33810 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74  or.** the collat
33820 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75  ion.  The destru
33830 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77  ctor is called w
33840 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  hen the collatio
33850 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65  n is.** destroye
33860 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20  d and is passed 
33870 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f  a copy of the fo
33880 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76  urth parameter v
33890 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  oid* pointer.** 
338a0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  of the sqlite3_c
338b0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
338c0 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69  v2()..** Collati
338d0 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65  ons are destroye
338e0 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  d when they are 
338f0 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61  overridden by la
33900 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  ter calls to the
33910 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72  .** collation cr
33920 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  eation functions
33930 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61   or when the [da
33940 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33950 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20  n] is closed.** 
33960 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
33970 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  lose()]..**.** I
33980 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
33990 20 7b 48 31 36 36 30 33 7d 20 41 20 73 75 63 63   {H16603} A succ
339a0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74  essful call to t
339b0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
339c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
339d0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c  ollation_v2(B,X,
339e0 45 2c 50 2c 46 2c 44 29 5d 20 69 6e 74 65 72 66  E,P,F,D)] interf
339f0 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ace.**          
33a00 72 65 67 69 73 74 65 72 73 20 66 75 6e 63 74 69  registers functi
33a10 6f 6e 20 46 20 61 73 20 74 68 65 20 63 6f 6d 70  on F as the comp
33a20 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  arison function 
33a30 75 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20  used to.**      
33a40 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74 20 63 6f      implement co
33a50 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 74 68 65  llation X on the
33a60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
33a70 63 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20  ction] B for.** 
33a80 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73           databas
33a90 65 73 20 68 61 76 69 6e 67 20 65 6e 63 6f 64 69  es having encodi
33aa0 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ng E..**.** {H16
33ab0 36 30 34 7d 20 53 51 4c 69 74 65 20 75 6e 64 65  604} SQLite unde
33ac0 72 73 74 61 6e 64 73 20 74 68 65 20 58 20 70 61  rstands the X pa
33ad0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20  rameter to.**   
33ae0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
33af0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33b00 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
33b10 5d 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  ] as a zero-term
33b20 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  inated.**       
33b30 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20     UTF-8 string 
33b40 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 69 73  in which case is
33b50 20 69 67 6e 6f 72 65 64 20 66 6f 72 20 41 53 43   ignored for ASC
33b60 49 49 20 63 68 61 72 61 63 74 65 72 73 20 61 6e  II characters an
33b70 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  d.**          is
33b80 20 73 69 67 6e 69 66 69 63 61 6e 74 20 66 6f 72   significant for
33b90 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61 72 61   non-ASCII chara
33ba0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  cters..**.** {H1
33bb0 36 36 30 36 7d 20 53 75 63 63 65 73 73 69 76 65  6606} Successive
33bc0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
33bd0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33be0 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
33bf0 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,D)].**         
33c00 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76   with the same v
33c10 61 6c 75 65 73 20 66 6f 72 20 42 2c 20 58 2c 20  alues for B, X, 
33c20 61 6e 64 20 45 2c 20 6f 76 65 72 72 69 64 65 20  and E, override 
33c30 70 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a 2a 20  prior values.** 
33c40 20 20 20 20 20 20 20 20 20 6f 66 20 50 2c 20 46           of P, F
33c50 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  , and D..**.** {
33c60 48 31 36 36 30 39 7d 20 49 66 20 74 68 65 20 64  H16609} If the d
33c70 65 73 74 72 75 63 74 6f 72 20 44 20 69 6e 20 5b  estructor D in [
33c80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
33c90 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c  ollation_v2(B,X,
33ca0 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20  E,P,F,D)].**    
33cb0 20 20 20 20 20 20 69 73 20 6e 6f 74 20 4e 55 4c        is not NUL
33cc0 4c 20 74 68 65 6e 20 69 74 20 69 73 20 63 61 6c  L then it is cal
33cd0 6c 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e  led with argumen
33ce0 74 20 50 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  t P when the.** 
33cf0 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69           collati
33d00 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  ng function is d
33d10 72 6f 70 70 65 64 20 62 79 20 53 51 4c 69 74 65  ropped by SQLite
33d20 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 32 7d  ..**.** {H16612}
33d30 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   A collating fun
33d40 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64  ction is dropped
33d50 20 77 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   when it is over
33d60 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  loaded..**.** {H
33d70 31 36 36 31 35 7d 20 41 20 63 6f 6c 6c 61 74 69  16615} A collati
33d80 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  ng function is d
33d90 72 6f 70 70 65 64 20 77 68 65 6e 20 74 68 65 20  ropped when the 
33da0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33db0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
33dc0 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20  is closed using 
33dd0 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
33de0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 38  ]..**.** {H16618
33df0 7d 20 54 68 65 20 70 6f 69 6e 74 65 72 20 50 20  } The pointer P 
33e00 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  in [sqlite3_crea
33e10 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
33e20 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a  B,X,E,P,F,D)].**
33e30 20 20 20 20 20 20 20 20 20 20 69 73 20 70 61 73            is pas
33e40 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
33e50 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
33e60 65 72 20 74 6f 20 74 68 65 20 63 6f 6d 70 61 72  er to the compar
33e70 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ison.**         
33e80 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20   function F for 
33e90 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69  all subsequent i
33ea0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 46 2e  nvocations of F.
33eb0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 31 7d 20  .**.** {H16621} 
33ec0 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
33ed0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33ee0 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20  ion(B,X,E,P,F)] 
33ef0 69 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20  is exactly.**   
33f00 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20         the same 
33f10 61 73 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  as a call to [sq
33f20 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33f30 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 20 77 69 74  lation_v2()] wit
33f40 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  h.**          th
33f50 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72  e same parameter
33f60 73 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64 65 73  s and a NULL des
33f70 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b  tructor..**.** {
33f80 48 31 36 36 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e  H16624} Followin
33f90 67 20 61 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  g a [sqlite3_cre
33fa0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
33fb0 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a  (B,X,E,P,F,D)],.
33fc0 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69  **          SQLi
33fd0 74 65 20 75 73 65 73 20 74 68 65 20 63 6f 6d 70  te uses the comp
33fe0 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  arison function 
33ff0 46 20 66 6f 72 20 61 6c 6c 20 74 65 78 74 20 63  F for all text c
34000 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20  omparison.**    
34010 20 20 20 20 20 20 6f 70 65 72 61 74 69 6f 6e 73        operations
34020 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
34030 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20  e connection] B 
34040 6f 6e 20 74 65 78 74 20 76 61 6c 75 65 73 20 74  on text values t
34050 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hat.**          
34060 75 73 65 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  use the collatin
34070 67 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 64  g sequence named
34080 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32   X..**.** {H1662
34090 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
340a0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
340b0 31 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 77  16(B,X,E,P,F)] w
340c0 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 0a 2a 2a  orks the same.**
340d0 20 20 20 20 20 20 20 20 20 20 61 73 20 5b 73 71            as [sq
340e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
340f0 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46  lation(B,X,E,P,F
34100 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
34110 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  he.**          c
34120 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 58 20  ollation name X 
34130 69 73 20 75 6e 64 65 72 73 74 6f 6f 64 20 61 73  is understood as
34140 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
34150 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
34160 20 20 20 20 20 20 20 20 20 69 6e 73 74 65 61 64           instead
34170 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a   of UTF-8..**.**
34180 20 7b 48 31 36 36 33 30 7d 20 57 68 65 6e 20 6d   {H16630} When m
34190 75 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72 69 73  ultiple comparis
341a0 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  on functions are
341b0 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 74   available for t
341c0 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he same.**      
341d0 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65      collating se
341e0 71 75 65 6e 63 65 2c 20 53 51 4c 69 74 65 20 63  quence, SQLite c
341f0 68 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65 20 77  hooses the one w
34200 68 6f 73 65 20 74 65 78 74 20 65 6e 63 6f 64 69  hose text encodi
34210 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ng.**          r
34220 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73  equires the leas
34230 74 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 76  t amount of conv
34240 65 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20  ersion from the 
34250 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20  default.**      
34260 20 20 20 20 74 65 78 74 20 65 6e 63 6f 64 69 6e      text encodin
34270 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  g of the databas
34280 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
34290 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
342a0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  on(.  sqlite3*, 
342b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
342c0 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
342d0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
342e0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
342f0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
34300 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
34310 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  t void*).);.int 
34320 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
34330 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73  ollation_v2(.  s
34340 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
34350 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
34360 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
34370 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
34380 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
34390 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
343a0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
343b0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
343c0 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69  roy)(void*).);.i
343d0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
343e0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
343f0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
34400 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c  nst void *zName,
34410 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
34420 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
34430 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
34440 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
34450 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
34460 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
34470 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
34480 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
34490 73 20 7b 48 31 36 37 30 30 7d 20 3c 53 32 30 33  s {H16700} <S203
344a0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f  00>.**.** To avo
344b0 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67  id having to reg
344c0 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74  ister all collat
344d0 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65  ion sequences be
344e0 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a  fore a database.
344f0 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20  ** can be used, 
34500 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63  a single callbac
34510 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  k function may b
34520 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  e registered wit
34530 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  h the.** [databa
34540 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
34550 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  o be called when
34560 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65  ever an undefine
34570 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  d collation.** s
34580 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69  equence is requi
34590 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  red..**.** If th
345a0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65  e function is re
345b0 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
345c0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  he sqlite3_colla
345d0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50  tion_needed() AP
345e0 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  I,.** then it is
345f0 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65   passed the name
34600 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63  s of undefined c
34610 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
34620 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a  es as strings.**
34630 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d   encoded in UTF-
34640 38 2e 20 7b 48 31 36 37 30 33 7d 20 49 66 20 73  8. {H16703} If s
34650 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
34660 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75  _needed16() is u
34670 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  sed,.** the name
34680 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  s are passed as 
34690 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e  UTF-16 in machin
346a0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
346b0 64 65 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  der..** A call t
346c0 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f  o either functio
346d0 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65  n replaces any e
346e0 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b  xisting callback
346f0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
34700 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
34710 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
34720 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
34730 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
34740 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
34750 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
34760 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
34770 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
34780 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
34790 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  16().  The secon
347a0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
347b0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
347c0 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74  nnection.  The t
347d0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
347e0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
347f0 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
34800 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  TF16BE],.** or [
34810 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
34820 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
34830 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66  most desirable f
34840 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
34850 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
34860 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
34870 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  ed.  The fourth 
34880 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
34890 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
348a0 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69  required collati
348b0 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a  on sequence..**.
348c0 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
348d0 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
348e0 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73  register the des
348f0 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75  ired collation u
34900 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
34910 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34920 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  n()], [sqlite3_c
34930 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
34940 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
34950 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
34960 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  ation_v2()]..**.
34970 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
34980 2a 0a 2a 2a 20 7b 48 31 36 37 30 32 7d 20 41 20  *.** {H16702} A 
34990 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
349a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  to [sqlite3_coll
349b0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44 2c 50  ation_needed(D,P
349c0 2c 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,F)].**         
349d0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   or [sqlite3_col
349e0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
349f0 44 2c 50 2c 46 29 5d 20 63 61 75 73 65 73 0a 2a  D,P,F)] causes.*
34a00 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
34a10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34a20 69 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f 6b 65  ion] D to invoke
34a30 20 63 61 6c 6c 62 61 63 6b 20 46 20 77 69 74 68   callback F with
34a40 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20   first.**       
34a50 20 20 20 70 61 72 61 6d 65 74 65 72 20 50 20 77     parameter P w
34a60 68 65 6e 65 76 65 72 20 69 74 20 6e 65 65 64 73  henever it needs
34a70 20 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75   a comparison fu
34a80 6e 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20  nction for a.** 
34a90 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69           collati
34aa0 6e 67 20 73 65 71 75 65 6e 63 65 20 74 68 61 74  ng sequence that
34ab0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f   it does not kno
34ac0 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b  w about..**.** {
34ad0 48 31 36 37 30 34 7d 20 45 61 63 68 20 73 75 63  H16704} Each suc
34ae0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
34af0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
34b00 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a  on_needed()] or.
34b10 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
34b20 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
34b30 65 65 64 65 64 31 36 28 29 5d 20 6f 76 65 72 72  eeded16()] overr
34b40 69 64 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  ides the callbac
34b50 6b 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20  k registered.** 
34b60 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20           on the 
34b70 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
34b80 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20 70 72  onnection] by pr
34b90 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65 69 74  ior calls to eit
34ba0 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
34bb0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
34bc0 20 7b 48 31 36 37 30 36 7d 20 54 68 65 20 6e 61   {H16706} The na
34bd0 6d 65 20 6f 66 20 74 68 65 20 72 65 71 75 65 73  me of the reques
34be0 74 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ted collating fu
34bf0 6e 63 74 69 6f 6e 20 70 61 73 73 65 64 20 69 6e  nction passed in
34c00 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
34c10 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
34c20 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
34c30 73 20 69 6e 20 55 54 46 2d 38 20 69 66 20 74 68  s in UTF-8 if th
34c40 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  e callback.**   
34c50 20 20 20 20 20 20 20 77 61 73 20 72 65 67 69 73         was regis
34c60 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  tered using [sql
34c70 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
34c80 65 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  eeded()] and.** 
34c90 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 20 55           is in U
34ca0 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
34cb0 65 20 6f 72 64 65 72 20 69 66 20 74 68 65 20 63  e order if the c
34cc0 61 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a 20 20  allback was.**  
34cd0 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
34ce0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
34cf0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
34d00 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ed16()]..*/.int 
34d10 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
34d20 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
34d30 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
34d40 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
34d50 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
34d60 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
34d70 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  r*).);.int sqlit
34d80 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
34d90 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ded16(.  sqlite3
34da0 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  *, .  void*,.  v
34db0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
34dc0 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
34dd0 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  ep,const void*).
34de0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
34df0 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
34e00 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
34e10 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
34e20 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
34e30 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
34e40 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
34e50 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
34e60 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
34e70 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
34e80 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
34e90 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
34ea0 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
34eb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
34ec0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
34ed0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34ee0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
34ef0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
34f00 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
34f10 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
34f20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
34f30 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
34f40 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
34f50 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
34f60 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
34f70 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
34f80 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
34f90 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
34fa0 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
34fb0 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
34fc0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
34fd0 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
34fe0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
34ff0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
35000 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
35010 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
35020 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
35030 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
35040 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
35050 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
35060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
35070 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
35080 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
35090 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
350a0 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
350b0 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
350c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
350d0 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  F: Suspend Execu
350e0 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
350f0 20 54 69 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c   Time {H10530} <
35100 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S40410>.**.** Th
35110 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  e sqlite3_sleep(
35120 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  ) function cause
35130 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68  s the current th
35140 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20  read to suspend 
35150 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72  execution.** for
35160 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62   at least a numb
35170 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
35180 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  ds specified in 
35190 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  its parameter..*
351a0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72  *.** If the oper
351b0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65  ating system doe
351c0 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c  s not support sl
351d0 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74  eep requests wit
351e0 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  h.** millisecond
351f0 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e   time resolution
35200 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20  , then the time 
35210 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20  will be rounded 
35220 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61  up to.** the nea
35230 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65  rest second. The
35240 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
35250 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
35260 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71   actually.** req
35270 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20  uested from the 
35280 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
35290 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
352a0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65  .** SQLite imple
352b0 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72  ments this inter
352c0 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20  face by calling 
352d0 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20  the xSleep().** 
352e0 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
352f0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
35300 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  fs] object..**.*
35310 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
35320 0a 2a 2a 20 7b 48 31 30 35 33 33 7d 20 54 68 65  .** {H10533} The
35330 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28   [sqlite3_sleep(
35340 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 6e  M)] interface in
35350 76 6f 6b 65 73 20 74 68 65 20 78 53 6c 65 65 70  vokes the xSleep
35360 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 74  .**          met
35370 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
35380 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 7c  lt [sqlite3_vfs|
35390 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  VFS] in order to
353a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 73  .**          sus
353b0 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 20 6f  pend execution o
353c0 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68  f the current th
353d0 72 65 61 64 20 66 6f 72 20 61 74 20 6c 65 61 73  read for at leas
353e0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d 20  t.**          M 
353f0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a  milliseconds..**
35400 0a 2a 2a 20 7b 48 31 30 35 33 36 7d 20 54 68 65  .** {H10536} The
35410 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28   [sqlite3_sleep(
35420 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  M)] interface re
35430 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
35440 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
35450 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
35460 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20 72  sleep actually r
35470 65 71 75 65 73 74 65 64 20 6f 66 20 74 68 65 20  equested of the 
35480 6f 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20 20 20  operating.**    
35490 20 20 20 20 20 20 73 79 73 74 65 6d 2c 20 77 68        system, wh
354a0 69 63 68 20 6d 69 67 68 74 20 62 65 20 6c 61 72  ich might be lar
354b0 67 65 72 20 74 68 61 6e 20 74 68 65 20 70 61 72  ger than the par
354c0 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74  ameter M..*/.int
354d0 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69   sqlite3_sleep(i
354e0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
354f0 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68  3REF: Name Of Th
35500 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67  e Folder Holding
35510 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73   Temporary Files
35520 20 7b 48 31 30 33 31 30 7d 20 3c 53 32 30 30 30   {H10310} <S2000
35530 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73  0>.**.** If this
35540 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
35550 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
35560 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
35570 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
35580 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
35590 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79  a.k.a. directory
355a0 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70  ), then all temp
355b0 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63  orary files.** c
355c0 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  reated by SQLite
355d0 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20   will be placed 
355e0 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72  in that director
355f0 79 2e 20 20 49 66 20 74 68 69 73 20 76 61 72 69  y.  If this vari
35600 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  able.** is a NUL
35610 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
35620 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20  SQLite performs 
35630 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20  a search for an 
35640 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74  appropriate.** t
35650 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69  emporary file di
35660 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  rectory..**.** I
35670 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
35680 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
35690 69 61 62 6c 65 20 6f 6e 63 65 20 61 20 5b 64 61  iable once a [da
356a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
356b0 6e 5d 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 6f  n].** has been o
356c0 70 65 6e 65 64 2e 20 20 49 74 20 69 73 20 69 6e  pened.  It is in
356d0 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73  tended that this
356e0 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74   variable be set
356f0 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74   once.** as part
35700 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74   of process init
35710 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62  ialization and b
35720 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65  efore any SQLite
35730 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f   interface.** ro
35740 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e  utines have been
35750 20 63 61 6c 6c 20 61 6e 64 20 72 65 6d 61 69 6e   call and remain
35760 20 75 6e 63 68 61 6e 67 65 64 20 74 68 65 72 65   unchanged there
35770 61 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45  after..*/.SQLITE
35780 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71  _EXTERN char *sq
35790 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
357a0 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tory;../*.** CAP
357b0 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20  I3REF: Test For 
357c0 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65  Auto-Commit Mode
357d0 20 7b 48 31 32 39 33 30 7d 20 3c 53 36 30 32 30   {H12930} <S6020
357e0 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
357f0 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  {autocommit mode
35800 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
35810 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
35820 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  it() interface r
35830 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20  eturns non-zero 
35840 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68  or.** zero if th
35850 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65  e given database
35860 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
35870 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f  r is not in auto
35880 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20  commit mode,.** 
35890 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41  respectively.  A
358a0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
358b0 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  s on by default.
358c0 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  .** Autocommit m
358d0 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  ode is disabled 
358e0 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61  by a [BEGIN] sta
358f0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63  tement..** Autoc
35900 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65  ommit mode is re
35910 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43  -enabled by a [C
35920 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42  OMMIT] or [ROLLB
35930 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63  ACK]..**.** If c
35940 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20  ertain kinds of 
35950 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20  errors occur on 
35960 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  a statement with
35970 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65  in a multi-state
35980 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ment.** transact
35990 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c  ion (errors incl
359a0 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55  uding [SQLITE_FU
359b0 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45  LL], [SQLITE_IOE
359c0 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  RR],.** [SQLITE_
359d0 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f  NOMEM], [SQLITE_
359e0 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  BUSY], and [SQLI
359f0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74  TE_INTERRUPT]) t
35a00 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73  hen the.** trans
35a10 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  action might be 
35a20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
35a30 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
35a40 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66  only way to.** f
35a50 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20  ind out whether 
35a60 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
35a70 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
35a80 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
35a90 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72   after.** an err
35aa0 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69  or is to use thi
35ab0 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
35ac0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
35ad0 0a 2a 2a 20 7b 48 31 32 39 33 31 7d 20 54 68 65  .** {H12931} The
35ae0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
35af0 74 6f 63 6f 6d 6d 69 74 28 44 29 5d 20 69 6e 74  tocommit(D)] int
35b00 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e  erface returns n
35b10 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 20 20  on-zero or.**   
35b20 20 20 20 20 20 20 20 7a 65 72 6f 20 69 66 20 74         zero if t
35b30 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
35b40 6e 65 63 74 69 6f 6e 5d 20 44 20 69 73 20 6f 72  nection] D is or
35b50 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63   is not in autoc
35b60 6f 6d 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 20  ommit.**        
35b70 20 20 6d 6f 64 65 2c 20 72 65 73 70 65 63 74 69    mode, respecti
35b80 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  vely..**.** {H12
35b90 39 33 32 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20  932} Autocommit 
35ba0 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65  mode is on by de
35bb0 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  fault..**.** {H1
35bc0 32 39 33 33 7d 20 41 75 74 6f 63 6f 6d 6d 69 74  2933} Autocommit
35bd0 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65   mode is disable
35be0 64 20 62 79 20 61 20 73 75 63 63 65 73 73 66 75  d by a successfu
35bf0 6c 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d  l [BEGIN] statem
35c00 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ent..**.** {H129
35c10 33 34 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  34} Autocommit m
35c20 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62  ode is enabled b
35c30 79 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b  y a successful [
35c40 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c  COMMIT] or [ROLL
35c50 42 41 43 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20  BACK].**        
35c60 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a    statement..**.
35c70 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
35c80 2a 2a 0a 2a 2a 20 7b 41 31 32 39 33 36 7d 20 49  **.** {A12936} I
35c90 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  f another thread
35ca0 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74   changes the aut
35cb0 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f  ocommit status o
35cc0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
35cd0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 6e 65  *          conne
35ce0 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73  ction while this
35cf0 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e   routine is runn
35d00 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
35d10 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20  turn value.**   
35d20 20 20 20 20 20 20 20 69 73 20 75 6e 64 65 66 69         is undefi
35d30 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
35d40 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
35d50 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  it(sqlite3*);../
35d60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
35d70 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65  ind The Database
35d80 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65   Handle Of A Pre
35d90 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
35da0 7b 48 31 33 31 32 30 7d 20 3c 53 36 30 36 30 30  {H13120} <S60600
35db0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
35dc0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e  te3_db_handle in
35dd0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
35de0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
35df0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
35e00 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b  .** to which a [
35e10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
35e20 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 54 68  nt] belongs.  Th
35e30 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
35e40 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  e returned by.**
35e50 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
35e60 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 64  le is the same d
35e70 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74  atabase handle t
35e80 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73  hat was the firs
35e90 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
35ea0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
35eb0 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c  epare_v2()] call
35ec0 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74   (or its variant
35ed0 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64  s) that was used
35ee0 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68   to.** create th
35ef0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  e statement in t
35f00 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a  he first place..
35f10 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
35f20 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 32 33 7d  :.**.** {H13123}
35f30 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   The [sqlite3_db
35f40 5f 68 61 6e 64 6c 65 28 53 29 5d 20 69 6e 74 65  _handle(S)] inte
35f50 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
35f60 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20  pointer.**      
35f70 20 20 20 20 74 6f 20 74 68 65 20 5b 64 61 74 61      to the [data
35f80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35f90 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
35fa0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
35fb0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
35fc0 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71 6c 69  ment] S..*/.sqli
35fd0 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f  te3 *sqlite3_db_
35fe0 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73  handle(sqlite3_s
35ff0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
36000 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65  PI3REF: Find the
36010 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73   next prepared s
36020 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 34 30  tatement {H13140
36030 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60600>.**.**
36040 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
36050 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
36060 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70  r to the next [p
36070 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36080 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d  t] after.** pStm
36090 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
360a0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
360b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e  connection] pDb.
360c0 20 20 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55    If pStmt is NU
360d0 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  LL.** then this 
360e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
360f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
36100 68 65 20 66 69 72 73 74 20 70 72 65 70 61 72 65  he first prepare
36110 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61  d statement.** a
36120 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
36130 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
36140 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 49 66 20  ection pDb.  If 
36150 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74  no prepared stat
36160 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69  ement.** satisfi
36170 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e  es the condition
36180 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
36190 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  e, it returns NU
361a0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  LL..**.** INVARI
361b0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
361c0 31 34 33 7d 20 49 66 20 44 20 69 73 20 61 20 5b  143} If D is a [
361d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
361e0 69 6f 6e 5d 20 74 68 61 74 20 68 6f 6c 64 73 20  ion] that holds 
361f0 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20  one or more.**  
36200 20 20 20 20 20 20 20 20 75 6e 66 69 6e 61 6c 69          unfinali
36210 7a 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  zed [prepared st
36220 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53 20  atements] and S 
36230 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
36240 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  r,.**          t
36250 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  hen [sqlite3_nex
36260 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f  t_stmt(D, S)] ro
36270 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75  utine shall retu
36280 72 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  rn a pointer.** 
36290 20 20 20 20 20 20 20 20 20 74 6f 20 6f 6e 65 20           to one 
362a0 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20  of the prepared 
362b0 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63  statements assoc
362c0 69 61 74 65 64 20 77 69 74 68 20 44 2e 0a 2a 2a  iated with D..**
362d0 0a 2a 2a 20 7b 48 31 33 31 34 36 7d 20 49 66 20  .** {H13146} If 
362e0 44 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  D is a [database
362f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
36300 74 20 68 6f 6c 64 73 20 6e 6f 20 75 6e 66 69 6e  t holds no unfin
36310 61 6c 69 7a 65 64 0a 2a 2a 20 20 20 20 20 20 20  alized.**       
36320 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
36330 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53 20 69  tements] and S i
36340 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
36350 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
36360 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74     [sqlite3_next
36370 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75  _stmt(D, S)] rou
36380 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72  tine shall retur
36390 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
363a0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 39 7d  ..**.** {H13149}
363b0 20 49 66 20 53 20 69 73 20 61 20 5b 70 72 65 70   If S is a [prep
363c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
363d0 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  in the [database
363e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
363f0 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 53  *          and S
36400 20 69 73 20 6e 6f 74 20 74 68 65 20 6c 61 73 74   is not the last
36410 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
36420 65 6e 74 20 69 6e 20 44 2c 20 74 68 65 6e 0a 2a  ent in D, then.*
36430 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
36440 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c  te3_next_stmt(D,
36450 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61   S)] routine sha
36460 6c 6c 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e  ll return a poin
36470 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
36480 74 6f 20 74 68 65 20 6e 65 78 74 20 70 72 65 70  to the next prep
36490 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
364a0 6e 20 44 20 61 66 74 65 72 20 53 2e 0a 2a 2a 0a  n D after S..**.
364b0 2a 2a 20 7b 48 31 33 31 35 32 7d 20 49 66 20 53  ** {H13152} If S
364c0 20 69 73 20 74 68 65 20 6c 61 73 74 20 5b 70 72   is the last [pr
364d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
364e0 5d 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  ] in the.**     
364f0 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
36500 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 68 65  onnection] D the
36510 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e  n the [sqlite3_n
36520 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 0a  ext_stmt(D, S)].
36530 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74  **          rout
36540 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  ine shall return
36550 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
36560 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f  .**.** ASSUMPTIO
36570 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 31 35  NS:.**.** {A1315
36580 34 7d 20 54 68 65 20 5b 64 61 74 61 62 61 73 65  4} The [database
36590 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69   connection] poi
365a0 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c  nter D in a call
365b0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
365c0 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
365d0 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65  mt(D,S)] must re
365e0 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64  fer to an open d
365f0 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20  atabase.**      
36600 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61      connection a
36610 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  nd in particular
36620 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e   must not be a N
36630 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a  ULL pointer..*/.
36640 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71  sqlite3_stmt *sq
36650 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
36660 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71  sqlite3 *pDb, sq
36670 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
36680 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
36690 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20  REF: Commit And 
366a0 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63  Rollback Notific
366b0 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20  ation Callbacks 
366c0 7b 48 31 32 39 35 30 7d 20 3c 53 36 30 34 30 30  {H12950} <S60400
366d0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
366e0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
366f0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
36700 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
36710 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
36720 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
36730 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
36740 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a  n is committed..
36750 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  ** Any callback 
36760 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
36770 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
36780 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a  3_commit_hook().
36790 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
367a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
367b0 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
367c0 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  n..** The sqlite
367d0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
367e0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
367f0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
36800 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
36810 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
36820 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
36830 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a  n is committed..
36840 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  ** Any callback 
36850 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
36860 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
36870 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a  3_commit_hook().
36880 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
36890 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
368a0 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
368b0 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67 20 61  n..** The pArg a
368c0 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65  rgument is passe
368d0 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
368e0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 49 66   callback..** If
368f0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e   the callback on
36900 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66   a commit hook f
36910 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
36920 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65  non-zero,.** the
36930 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20  n the commit is 
36940 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
36950 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
36960 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63   If another func
36970 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75  tion was previou
36980 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20  sly registered, 
36990 69 74 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75  its.** pArg valu
369a0 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
369b0 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69  Otherwise NULL i
369c0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
369d0 2a 20 52 65 67 69 73 74 65 72 69 6e 67 20 61 20  * Registering a 
369e0 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69  NULL function di
369f0 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62  sables the callb
36a00 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74  ack..**.** For t
36a10 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
36a20 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73  his API, a trans
36a30 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74  action is said t
36a40 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72  o have been.** r
36a50 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e  olled back if an
36a60 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42   explicit "ROLLB
36a70 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69  ACK" statement i
36a80 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a  s executed, or.*
36a90 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f  * an error or co
36aa0 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20  nstraint causes 
36ab0 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c  an implicit roll
36ac0 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a  back to occur..*
36ad0 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63  * The rollback c
36ae0 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69  allback is not i
36af0 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e  nvoked if a tran
36b00 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75  saction is.** au
36b10 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
36b20 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20  ed back because 
36b30 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
36b40 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
36b50 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61  d..** The rollba
36b60 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ck callback is n
36b70 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20  ot invoked if a 
36b80 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a  transaction is.*
36b90 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65  * rolled back be
36ba0 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20 63  cause a commit c
36bb0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65 64  allback returned
36bc0 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74   non-zero..** <t
36bd0 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68  odo> Check on th
36be0 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  is </todo>.**.**
36bf0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
36c00 2a 2a 20 7b 48 31 32 39 35 31 7d 20 54 68 65 20  ** {H12951} The 
36c10 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
36c20 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
36c30 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
36c40 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
36c50 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
36c60 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on F to be invok
36c70 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
36c80 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20   P whenever.**  
36c90 20 20 20 20 20 20 20 20 61 20 74 72 61 6e 73 61          a transa
36ca0 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 20 6f 6e  ction commits on
36cb0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
36cc0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
36cd0 0a 2a 2a 20 7b 48 31 32 39 35 32 7d 20 54 68 65  .** {H12952} The
36ce0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   [sqlite3_commit
36cf0 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e  _hook(D,F,P)] in
36d00 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
36d10 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 0a 2a  the P argument.*
36d20 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20  *          from 
36d30 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
36d40 6c 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  l with the same 
36d50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36d60 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20 20  tion] D,.**     
36d70 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20       or NULL on 
36d80 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66  the first call f
36d90 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
36da0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36db0 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ion D..**.** {H1
36dc0 32 39 35 33 7d 20 45 61 63 68 20 63 61 6c 6c 20  2953} Each call 
36dd0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  to [sqlite3_comm
36de0 69 74 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77  it_hook()] overw
36df0 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61  rites the callba
36e00 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ck.**          r
36e10 65 67 69 73 74 65 72 65 64 20 62 79 20 70 72 69  egistered by pri
36e20 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20  or calls..**.** 
36e30 7b 48 31 32 39 35 34 7d 20 49 66 20 74 68 65 20  {H12954} If the 
36e40 46 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  F argument to [s
36e50 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
36e60 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55  ok(D,F,P)] is NU
36e70 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  LL.**          t
36e80 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  hen the commit h
36e90 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ook callback is 
36ea0 63 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20  canceled and no 
36eb0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
36ec0 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20       is invoked 
36ed0 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63 74 69  when a transacti
36ee0 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a 2a 2a 0a 2a  on commits..**.*
36ef0 2a 20 7b 48 31 32 39 35 35 7d 20 49 66 20 74 68  * {H12955} If th
36f00 65 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63  e commit callbac
36f10 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
36f20 72 6f 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d  ro then the comm
36f30 69 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  it is.**        
36f40 20 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f    converted into
36f50 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a   a rollback..**.
36f60 2a 2a 20 7b 48 31 32 39 36 31 7d 20 54 68 65 20  ** {H12961} The 
36f70 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
36f80 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  k_hook(D,F,P)] i
36f90 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
36fa0 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  rs the.**       
36fb0 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63     callback func
36fc0 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76  tion F to be inv
36fd0 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65  oked with argume
36fe0 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a  nt P whenever.**
36ff0 20 20 20 20 20 20 20 20 20 20 61 20 74 72 61 6e            a tran
37000 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61  saction rolls ba
37010 63 6b 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ck on the [datab
37020 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37030 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 32  D..**.** {H12962
37040 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
37050 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46  ollback_hook(D,F
37060 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,P)] interface r
37070 65 74 75 72 6e 73 20 74 68 65 20 50 0a 2a 2a 20  eturns the P.** 
37080 20 20 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e           argumen
37090 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69  t from the previ
370a0 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74 68  ous call with th
370b0 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
370c0 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
370d0 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e  nection] D, or N
370e0 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ULL on the first
370f0 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20   call.**        
37100 20 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c    for a particul
37110 61 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ar database conn
37120 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20  ection D..**.** 
37130 7b 48 31 32 39 36 33 7d 20 45 61 63 68 20 63 61  {H12963} Each ca
37140 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
37150 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 20  ollback_hook()] 
37160 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 20 63  overwrites the c
37170 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  allback.**      
37180 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 62      registered b
37190 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a  y prior calls..*
371a0 2a 0a 2a 2a 20 7b 48 31 32 39 36 34 7d 20 49 66  *.** {H12964} If
371b0 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e 74 20   the F argument 
371c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  to [sqlite3_roll
371d0 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  back_hook(D,F,P)
371e0 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20  ] is NULL.**    
371f0 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 72        then the r
37200 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c  ollback hook cal
37210 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 65  lback is cancele
37220 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63  d and no callbac
37230 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  k.**          is
37240 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
37250 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c  transaction roll
37260 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76 6f 69 64 20  s back..*/.void 
37270 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  *sqlite3_commit_
37280 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69  hook(sqlite3*, i
37290 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
372a0 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  id*);.void *sqli
372b0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
372c0 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  k(sqlite3*, void
372d0 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69  (*)(void *), voi
372e0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
372f0 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67  3REF: Data Chang
37300 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  e Notification C
37310 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 37 30  allbacks {H12970
37320 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60400>.**.**
37330 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64   The sqlite3_upd
37340 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ate_hook() inter
37350 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
37360 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
37370 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
37380 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37390 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20  ion] identified 
373a0 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
373b0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69  ument.** to be i
373c0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
373d0 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  a row is updated
373e0 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
373f0 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61  leted..** Any ca
37400 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
37410 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
37420 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
37430 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
37440 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37450 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
37460 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
37470 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  nd argument is a
37480 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
37490 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f  function to invo
374a0 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77  ke when a.** row
374b0 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73   is updated, ins
374c0 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
374d0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
374e0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
374f0 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
37500 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61  y of the third a
37510 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71  rgument.** to sq
37520 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
37530 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  k()..** The seco
37540 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75  nd callback argu
37550 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
37560 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
37570 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c  [SQLITE_DELETE],
37580 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
37590 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e  PDATE], dependin
375a0 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
375b0 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
375c0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  he callback.** t
375d0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
375e0 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66   The third and f
375f0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20  ourth arguments 
37600 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
37610 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73  contain pointers
37620 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
37630 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61  ase and table na
37640 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  me containing th
37650 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a  e affected row..
37660 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  ** The final cal
37670 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
37680 69 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  is the rowid of 
37690 74 68 65 20 72 6f 77 2e 20 49 6e 20 74 68 65 20  the row. In the 
376a0 63 61 73 65 20 6f 66 0a 2a 2a 20 61 6e 20 75 70  case of.** an up
376b0 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68  date, this is th
376c0 65 20 72 6f 77 69 64 20 61 66 74 65 72 20 74 68  e rowid after th
376d0 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70  e update takes p
376e0 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lace..**.** The 
376f0 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e  update hook is n
37700 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ot invoked when 
37710 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20  internal system 
37720 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f  tables are.** mo
37730 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c  dified (i.e. sql
37740 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73  ite_master and s
37750 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e  qlite_sequence).
37760 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65  .**.** If anothe
37770 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70  r function was p
37780 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
37790 65 72 65 64 2c 20 69 74 73 20 70 41 72 67 20 76  ered, its pArg v
377a0 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74 75 72  alue.** is retur
377b0 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
377c0 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
377d0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
377e0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37  TS:.**.** {H1297
377f0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
37800 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c  update_hook(D,F,
37810 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61  P)] interface ca
37820 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  uses the callbac
37830 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75  k.**          fu
37840 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69  nction F to be i
37850 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 69 72 73  nvoked with firs
37860 74 20 70 61 72 61 6d 65 74 65 72 20 50 20 77 68  t parameter P wh
37870 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20  enever.**       
37880 20 20 20 61 20 74 61 62 6c 65 20 72 6f 77 20 69     a table row i
37890 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65  s modified, inse
378a0 72 74 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64  rted, or deleted
378b0 20 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   on.**          
378c0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
378d0 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
378e0 2a 2a 20 7b 48 31 32 39 37 33 7d 20 54 68 65 20  ** {H12973} The 
378f0 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
37900 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
37910 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
37920 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20  he value.**     
37930 20 20 20 20 20 6f 66 20 50 20 66 6f 72 20 74 68       of P for th
37940 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
37950 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
37960 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37970 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] D,.**         
37980 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 20 74 68 65   or NULL for the
37990 20 66 69 72 73 74 20 63 61 6c 6c 2e 0a 2a 2a 0a   first call..**.
379a0 2a 2a 20 7b 48 31 32 39 37 35 7d 20 49 66 20 74  ** {H12975} If t
379b0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 63  he update hook c
379c0 61 6c 6c 62 61 63 6b 20 46 20 69 6e 20 5b 73 71  allback F in [sq
379d0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
379e0 6b 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20 20 20  k(D,F,P)].**    
379f0 20 20 20 20 20 20 69 73 20 4e 55 4c 4c 20 74 68        is NULL th
37a00 65 6e 20 74 68 65 20 6e 6f 20 75 70 64 61 74 65  en the no update
37a10 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6d   callbacks are m
37a20 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ade..**.** {H129
37a30 37 37 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  77} Each call to
37a40 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   [sqlite3_update
37a50 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 6f 76  _hook(D,F,P)] ov
37a60 65 72 72 69 64 65 73 20 70 72 69 6f 72 20 63 61  errides prior ca
37a70 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lls.**          
37a80 74 6f 20 74 68 65 20 73 61 6d 65 20 69 6e 74 65  to the same inte
37a90 72 66 61 63 65 20 6f 6e 20 74 68 65 20 73 61 6d  rface on the sam
37aa0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37ab0 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
37ac0 20 7b 48 31 32 39 37 39 7d 20 54 68 65 20 75 70   {H12979} The up
37ad0 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61  date hook callba
37ae0 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ck is not invoke
37af0 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20  d when internal 
37b00 73 79 73 74 65 6d 0a 2a 2a 20 20 20 20 20 20 20  system.**       
37b10 20 20 20 74 61 62 6c 65 73 20 73 75 63 68 20 61     tables such a
37b20 73 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20  s sqlite_master 
37b30 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65  and sqlite_seque
37b40 6e 63 65 20 61 72 65 20 6d 6f 64 69 66 69 65 64  nce are modified
37b50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 38 31 7d  ..**.** {H12981}
37b60 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
37b70 6d 65 74 65 72 20 74 6f 20 74 68 65 20 75 70 64  meter to the upd
37b80 61 74 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ate callback.** 
37b90 20 20 20 20 20 20 20 20 20 69 73 20 6f 6e 65 20           is one 
37ba0 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52  of [SQLITE_INSER
37bb0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45  T], [SQLITE_DELE
37bc0 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  TE] or [SQLITE_U
37bd0 50 44 41 54 45 5d 2c 0a 2a 2a 20 20 20 20 20 20  PDATE],.**      
37be0 20 20 20 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e      depending on
37bf0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74   the operation t
37c00 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63  hat caused the c
37c10 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 69 6e  allback to be in
37c20 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  voked..**.** {H1
37c30 32 39 38 33 7d 20 54 68 65 20 74 68 69 72 64 20  2983} The third 
37c40 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d  and fourth argum
37c50 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ents to the call
37c60 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69  back contain poi
37c70 6e 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  nters.**        
37c80 20 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e    to zero-termin
37c90 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
37ca0 67 73 20 77 68 69 63 68 20 61 72 65 20 74 68 65  gs which are the
37cb0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
37cc0 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61            databa
37cd0 73 65 20 61 6e 64 20 74 61 62 6c 65 20 74 68 61  se and table tha
37ce0 74 20 69 73 20 62 65 69 6e 67 20 75 70 64 61 74  t is being updat
37cf0 65 64 2e 0a 0a 2a 2a 20 7b 48 31 32 39 38 35 7d  ed...** {H12985}
37d00 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62   The final callb
37d10 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ack parameter is
37d20 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
37d30 65 20 72 6f 77 20 61 66 74 65 72 0a 2a 2a 20 20  e row after.**  
37d40 20 20 20 20 20 20 20 20 74 68 65 20 63 68 61 6e          the chan
37d50 67 65 20 6f 63 63 75 72 73 2e 0a 2a 2f 0a 76 6f  ge occurs..*/.vo
37d60 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61  id *sqlite3_upda
37d70 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74  te_hook(.  sqlit
37d80 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  e3*, .  void(*)(
37d90 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72  void *,int ,char
37da0 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f   const *,char co
37db0 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  nst *,sqlite3_in
37dc0 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b  t64),.  void*.);
37dd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37de0 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
37df0 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72  ble Shared Pager
37e00 20 43 61 63 68 65 20 7b 48 31 30 33 33 30 7d 20   Cache {H10330} 
37e10 3c 53 33 30 39 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S30900>.** KEYW
37e20 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63 61  ORDS: {shared ca
37e30 63 68 65 7d 20 7b 73 68 61 72 65 64 20 63 61 63  che} {shared cac
37e40 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54  he mode}.**.** T
37e50 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  his routine enab
37e60 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
37e70 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74  the sharing of t
37e80 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68  he database cach
37e90 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20  e.** and schema 
37ea0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
37eb0 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73  between [databas
37ec0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63  e connection | c
37ed0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74  onnections].** t
37ee0 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
37ef0 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20  ase. Sharing is 
37f00 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  enabled if the a
37f10 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a  rgument is true.
37f20 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20  ** and disabled 
37f30 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  if the argument 
37f40 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20  is false..**.** 
37f50 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 73  Cache sharing is
37f60 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73   enabled and dis
37f70 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e 74  abled for an ent
37f80 69 72 65 20 70 72 6f 63 65 73 73 2e 20 7b 45 4e  ire process. {EN
37f90 44 7d 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  D}.** This is a 
37fa0 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c  change as of SQL
37fb0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
37fc0 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73  0. In prior vers
37fd0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a  ions of SQLite,.
37fe0 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65  ** sharing was e
37ff0 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
38000 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65  ed for each thre
38010 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  ad separately..*
38020 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73  *.** The cache s
38030 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20  haring mode set 
38040 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  by this interfac
38050 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75  e effects all su
38060 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
38070 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  s to [sqlite3_op
38080 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
38090 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
380a0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
380b0 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  )]..** Existing 
380c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
380d0 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73  ions continue us
380e0 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  e the sharing mo
380f0 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69  de.** that was i
38100 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20  n effect at the 
38110 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f  time they were o
38120 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56 69 72  pened..**.** Vir
38130 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 6e  tual tables cann
38140 6f 74 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ot be used with 
38150 61 20 73 68 61 72 65 64 20 63 61 63 68 65 2e 20  a shared cache. 
38160 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a 2a 20   When shared.** 
38170 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
38180 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  , the [sqlite3_c
38190 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20  reate_module()] 
381a0 41 50 49 20 75 73 65 64 20 74 6f 20 72 65 67 69  API used to regi
381b0 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61 6c 20  ster.** virtual 
381c0 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c 77 61  tables will alwa
381d0 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  ys return an err
381e0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  or..**.** This r
381f0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
38200 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68  SQLITE_OK] if sh
38210 61 72 65 64 20 63 61 63 68 65 20 77 61 73 20 65  ared cache was e
38220 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
38230 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ed.** successful
38240 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72 20 63  ly.  An [error c
38250 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
38260 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
38270 2a 20 53 68 61 72 65 64 20 63 61 63 68 65 20 69  * Shared cache i
38280 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
38290 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20  fault. But this 
382a0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a  might change in.
382b0 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ** future releas
382c0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  es of SQLite.  A
382d0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
382e0 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72   care about shar
382f0 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74  ed.** cache sett
38300 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69  ing should set i
38310 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a  t explicitly..**
38320 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
38330 2a 2a 0a 2a 2a 20 7b 48 31 30 33 33 31 7d 20 41  **.** {H10331} A
38340 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
38350 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
38360 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
38370 5f 63 61 63 68 65 28 42 29 5d 0a 2a 2a 20 20 20  _cache(B)].**   
38380 20 20 20 20 20 20 20 77 69 6c 6c 20 65 6e 61 62         will enab
38390 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 73 68  le or disable sh
383a0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 20  ared cache mode 
383b0 66 6f 72 20 61 6e 79 20 73 75 62 73 65 71 75 65  for any subseque
383c0 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ntly.**         
383d0 20 63 72 65 61 74 65 64 20 5b 64 61 74 61 62 61   created [databa
383e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
383f0 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65  n the same proce
38400 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 33 33  ss..**.** {H1033
38410 36 7d 20 57 68 65 6e 20 73 68 61 72 65 64 20 63  6} When shared c
38420 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 2c  ache is enabled,
38430 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
38440 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 0a 2a  eate_module()].*
38450 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
38460 66 61 63 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  face will always
38470 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72   return an error
38480 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 33 33 37 7d  ..**.** {H10337}
38490 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e   The [sqlite3_en
384a0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
384b0 65 28 42 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(B)] interface 
384c0 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
384d0 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20      [SQLITE_OK] 
384e0 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20  if shared cache 
384f0 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  was enabled or d
38500 69 73 61 62 6c 65 64 20 73 75 63 63 65 73 73 66  isabled successf
38510 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  ully..**.** {H10
38520 33 33 39 7d 20 53 68 61 72 65 64 20 63 61 63 68  339} Shared cach
38530 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
38540 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69 6e 74   default..*/.int
38550 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
38560 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e 74  shared_cache(int
38570 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
38580 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f 20 46  EF: Attempt To F
38590 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79 20  ree Heap Memory 
385a0 7b 48 31 37 33 34 30 7d 20 3c 53 33 30 32 32 30  {H17340} <S30220
385b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
385c0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
385d0 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  ry() interface a
385e0 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20  ttempts to free 
385f0 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68 65  N bytes.** of he
38600 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61  ap memory by dea
38610 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73  llocating non-es
38620 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20 61  sential memory a
38630 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68 65  llocations.** he
38640 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61  ld by the databa
38650 73 65 20 6c 69 62 72 61 72 79 2e 20 7b 45 4e 44  se library. {END
38660 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74  }  Memory used t
38670 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65  o cache database
38680 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70  .** pages to imp
38690 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  rove performance
386a0 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   is an example o
386b0 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20  f non-essential 
386c0 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 73 71 6c 69 74  memory..** sqlit
386d0 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
386e0 79 28 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  y() returns the 
386f0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
38700 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a  actually freed,.
38710 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20 62  ** which might b
38720 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74  e more or less t
38730 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72  han the amount r
38740 65 71 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  equested..**.** 
38750 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
38760 2a 20 7b 48 31 37 33 34 31 7d 20 54 68 65 20 5b  * {H17341} The [
38770 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
38780 6d 65 6d 6f 72 79 28 4e 29 5d 20 69 6e 74 65 72  memory(N)] inter
38790 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
387a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 65  .**          fre
387b0 65 20 4e 20 62 79 74 65 73 20 6f 66 20 68 65 61  e N bytes of hea
387c0 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65 61 6c  p memory by deal
387d0 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65 73 73  locating non-ess
387e0 65 6e 74 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20  ential.**       
387f0 20 20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61     memory alloca
38800 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20 74 68  tions held by th
38810 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61  e database libra
38820 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 33 34  ry..**.** {H1634
38830 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
38840 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e  release_memory(N
38850 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  )] returns the n
38860 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  umber.**        
38870 20 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61    of bytes actua
38880 6c 6c 79 20 66 72 65 65 64 2c 20 77 68 69 63 68  lly freed, which
38890 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f   might be more o
388a0 72 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 20  r less.**       
388b0 20 20 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75     than the amou
388c0 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2f  nt requested..*/
388d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c  .int sqlite3_rel
388e0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29  ease_memory(in