/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact b6f0bb400e82d271709412ab59ee898d6a4c196a:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f  rve to make mino
03c0: 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a 20  r changes if.** 
03d0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20  experience from 
03e0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64  use "in the wild
03f0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63  " suggest such c
0400: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65  hanges are prude
0410: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66  nt..**.** The of
0420: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67  ficial C-languag
0430: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74  e API documentat
0440: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69  ion for SQLite i
0450: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f  s derived.** fro
0460: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68  m comments in th
0470: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66  is file.  This f
0480: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f  ile is the autho
0490: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a  ritative source.
04a0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65  ** on how SQLite
04b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
04c0: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61  suppose to opera
04d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  te..**.** The na
04e0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  me of this file 
04f0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74  under configurat
0500: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69  ion management i
0510: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e  s "sqlite.h.in".
0520: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65  .** The makefile
0530: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f   makes some mino
0540: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69  r changes to thi
0550: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20  s file (such as 
0560: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65  inserting.** the
0570: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29   version number)
0580: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73   and changes its
0590: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65   name to "sqlite
05a0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20  3.h" as.** part 
05b0: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f  of the build pro
05c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 29  cess..**.** @(#)
05d0: 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e 69   $Id: sqlite.h.i
05e0: 6e 2c 76 20 31 2e 33 38 37 20 32 30 30 38 2f 30  n,v 1.387 2008/0
05f0: 38 2f 30 35 20 31 37 3a 35 33 3a 32 33 20 64 72  8/05 17:53:23 dr
0600: 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e 64  h Exp $.*/.#ifnd
0610: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ef _SQLITE3_H_.#
0620: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f  define _SQLITE3_
0630: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64  H_.#include <std
0640: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65  arg.h>     /* Ne
0650: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66  eded for the def
0660: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69  inition of va_li
0670: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  st */../*.** Mak
0680: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61  e sure we can ca
0690: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72  ll this stuff fr
06a0: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65  om C++..*/.#ifde
06b0: 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78  f __cplusplus.ex
06c0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69  tern "C" {.#endi
06d0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68  f.../*.** Add th
06e0: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65  e ability to ove
06f0: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a  rride 'extern'.*
0700: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
0710: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65  _EXTERN.# define
0720: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65   SQLITE_EXTERN e
0730: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  xtern.#endif../*
0740: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0750: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0760: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0770: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0780: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0790: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
07a0: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
07b0: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
07c0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
07d0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
07e0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
07f0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0800: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0810: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0820: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0830: 75 6d 62 65 72 73 20 7b 48 31 30 30 31 30 7d 20  umbers {H10010} 
0840: 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60100>.**.** T
0850: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0860: 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f 56 45 52  N and SQLITE_VER
0870: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 64 65 66  SION_NUMBER #def
0880: 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68 65 20 73  ines in.** the s
0890: 71 6c 69 74 65 33 2e 68 20 66 69 6c 65 20 73 70  qlite3.h file sp
08a0: 65 63 69 66 79 20 74 68 65 20 76 65 72 73 69 6f  ecify the versio
08b0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 77 69 74 68  n of SQLite with
08c0: 20 77 68 69 63 68 0a 2a 2a 20 74 68 61 74 20 68   which.** that h
08d0: 65 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73  eader file is as
08e0: 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  sociated..**.** 
08f0: 54 68 65 20 22 76 65 72 73 69 6f 6e 22 20 6f 66  The "version" of
0900: 20 53 51 4c 69 74 65 20 69 73 20 61 20 73 74 72   SQLite is a str
0910: 69 6e 67 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ing of the form 
0920: 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54 68 65 20  "X.Y.Z"..** The 
0930: 70 68 72 61 73 65 20 22 61 6c 70 68 61 22 20 6f  phrase "alpha" o
0940: 72 20 22 62 65 74 61 22 20 6d 69 67 68 74 20 62  r "beta" might b
0950: 65 20 61 70 70 65 6e 64 65 64 20 61 66 74 65 72  e appended after
0960: 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68 65 20 58   the Z..** The X
0970: 20 76 61 6c 75 65 20 69 73 20 6d 61 6a 6f 72 20   value is major 
0980: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0990: 6c 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69 74  lways 3 in SQLit
09a0: 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c  e3..** The X val
09b0: 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20  ue only changes 
09c0: 77 68 65 6e 20 62 61 63 6b 77 61 72 64 73 20 63  when backwards c
09d0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73 0a  ompatibility is.
09e0: 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77 65  ** broken and we
09f0: 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65 72   intend to never
0a00: 20 62 72 65 61 6b 20 62 61 63 6b 77 61 72 64 73   break backwards
0a10: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
0a20: 2a 2a 20 54 68 65 20 59 20 76 61 6c 75 65 20 69  ** The Y value i
0a30: 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73  s the minor vers
0a40: 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 6f  ion number and o
0a50: 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 6e  nly changes when
0a60: 0a 2a 2a 20 74 68 65 72 65 20 61 72 65 20 6d 61  .** there are ma
0a70: 6a 6f 72 20 66 65 61 74 75 72 65 20 65 6e 68 61  jor feature enha
0a80: 6e 63 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72  ncements that ar
0a90: 65 20 66 6f 72 77 61 72 64 73 20 63 6f 6d 70 61  e forwards compa
0aa0: 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e 6f 74  tible.** but not
0ab0: 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
0ac0: 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 5a 20  tible..** The Z 
0ad0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 72 65 6c  value is the rel
0ae0: 65 61 73 65 20 6e 75 6d 62 65 72 20 61 6e 64 20  ease number and 
0af0: 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 77  is incremented w
0b00: 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 65 6c 65  ith.** each rele
0b10: 61 73 65 20 62 75 74 20 72 65 73 65 74 73 20 62  ase but resets b
0b20: 61 63 6b 20 74 6f 20 30 20 77 68 65 6e 65 76 65  ack to 0 wheneve
0b30: 72 20 59 20 69 73 20 69 6e 63 72 65 6d 65 6e 74  r Y is increment
0b40: 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ed..**.** See al
0b50: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
0b60: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
0b70: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
0b80: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e 0a 2a 2a  on_number()]..**
0b90: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
0ba0: 2a 2a 0a 2a 2a 20 7b 48 31 30 30 31 31 7d 20 54  **.** {H10011} T
0bb0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0bc0: 4e 20 23 64 65 66 69 6e 65 20 69 6e 20 74 68 65  N #define in the
0bd0: 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65   sqlite3.h heade
0be0: 72 20 66 69 6c 65 20 73 68 61 6c 6c 0a 2a 2a 20  r file shall.** 
0bf0: 20 20 20 20 20 20 20 20 20 65 76 61 6c 75 61 74           evaluat
0c00: 65 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  e to a string li
0c10: 74 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68  teral that is th
0c20: 65 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  e SQLite version
0c30: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
0c40: 68 20 77 68 69 63 68 20 74 68 65 20 68 65 61 64  h which the head
0c50: 65 72 20 66 69 6c 65 20 69 73 20 61 73 73 6f 63  er file is assoc
0c60: 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  iated..**.** {H1
0c70: 30 30 31 34 7d 20 54 68 65 20 53 51 4c 49 54 45  0014} The SQLITE
0c80: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0c90: 23 64 65 66 69 6e 65 20 73 68 61 6c 6c 20 72 65  #define shall re
0ca0: 73 6f 6c 76 65 20 74 6f 20 61 6e 20 69 6e 74 65  solve to an inte
0cb0: 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ger.**          
0cc0: 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20 28  with the value (
0cd0: 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30  X*1000000 + Y*10
0ce0: 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c  00 + Z) where X,
0cf0: 20 59 2c 20 61 6e 64 20 5a 0a 2a 2a 20 20 20 20   Y, and Z.**    
0d00: 20 20 20 20 20 20 61 72 65 20 74 68 65 20 6d 61        are the ma
0d10: 6a 6f 72 20 76 65 72 73 69 6f 6e 2c 20 6d 69 6e  jor version, min
0d20: 6f 72 20 76 65 72 73 69 6f 6e 2c 20 61 6e 64 20  or version, and 
0d30: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 0a  release number..
0d40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0d50: 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20  E_VERSION       
0d60: 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65    "--VERS--".#de
0d70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
0d80: 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 2d 2d 56 45  ION_NUMBER  --VE
0d90: 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 0a  RSION-NUMBER--..
0da0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
0db0: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
0dc0: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
0dd0: 20 7b 48 31 30 30 32 30 7d 20 3c 53 36 30 31 30   {H10020} <S6010
0de0: 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
0df0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a  sqlite3_version.
0e00: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 65 61 74  **.** These feat
0e10: 75 72 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  ures provide the
0e20: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
0e30: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
0e40: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 61 6e 64  _VERSION].** and
0e50: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0e60: 5f 4e 55 4d 42 45 52 5d 20 23 64 65 66 69 6e 65  _NUMBER] #define
0e70: 73 20 69 6e 20 74 68 65 20 68 65 61 64 65 72 2c  s in the header,
0e80: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
0e90: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
0ea0: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
0eb0: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
0ec0: 6c 65 2e 20 20 43 61 75 74 69 6f 75 73 20 70 72  le.  Cautious pr
0ed0: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 0a  ogrammers might.
0ee0: 2a 2a 20 69 6e 63 6c 75 64 65 20 61 20 63 68 65  ** include a che
0ef0: 63 6b 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c  ck in their appl
0f00: 69 63 61 74 69 6f 6e 20 74 6f 20 76 65 72 69 66  ication to verif
0f10: 79 20 74 68 61 74 0a 2a 2a 20 73 71 6c 69 74 65  y that.** sqlite
0f20: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
0f30: 62 65 72 28 29 20 61 6c 77 61 79 73 20 72 65 74  ber() always ret
0f40: 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 0a 2a  urns the value.*
0f50: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  * [SQLITE_VERSIO
0f60: 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a  N_NUMBER]..**.**
0f70: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62   The sqlite3_lib
0f80: 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69  version() functi
0f90: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  on returns the s
0fa0: 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
0fb0: 61 73 20 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20  as is.** in the 
0fc0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
0fd0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
0fe0: 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e  t.  The function
0ff0: 20 69 73 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20   is provided.** 
1000: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
1010: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
1020: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
1030: 61 76 65 20 64 69 72 65 63 74 20 61 63 63 65 73  ave direct acces
1040: 73 20 74 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63  s to string.** c
1050: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
1060: 74 68 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49  the DLL..**.** I
1070: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1080: 20 7b 48 31 30 30 32 31 7d 20 54 68 65 20 5b 73   {H10021} The [s
1090: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
10a0: 6e 5f 6e 75 6d 62 65 72 28 29 5d 20 69 6e 74 65  n_number()] inte
10b0: 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75  rface shall retu
10c0: 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  rn.**          a
10d0: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
10e0: 74 6f 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  to [SQLITE_VERSI
10f0: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a  ON_NUMBER]..**.*
1100: 2a 20 7b 48 31 30 30 32 32 7d 20 54 68 65 20 5b  * {H10022} The [
1110: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5d  sqlite3_version]
1120: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1130: 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 0a 2a   shall contain.*
1140: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 74  *          the t
1150: 65 78 74 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ext of the [SQLI
1160: 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73 74 72 69  TE_VERSION] stri
1170: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32  ng..**.** {H1002
1180: 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
1190: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 66 75  libversion()] fu
11a0: 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74  nction shall ret
11b0: 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
11c0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
11d0: 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f   [sqlite3_versio
11e0: 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  n] string consta
11f0: 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  nt..*/.SQLITE_EX
1200: 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20  TERN const char 
1210: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
1220: 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  ];.const char *s
1230: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1240: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
1250: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1260: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1280: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1290: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
12a0: 65 61 64 73 61 66 65 20 7b 48 31 30 31 30 30 7d  eadsafe {H10100}
12b0: 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S60100>.**.** 
12c0: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f  SQLite can be co
12d0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77  mpiled with or w
12e0: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20  ithout mutexes. 
12f0: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51   When.** the [SQ
1300: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1310: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1320: 6d 61 63 72 6f 20 69 73 20 74 72 75 65 2c 20 6d  macro is true, m
1330: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
1340: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
1350: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
1360: 20 57 68 65 6e 20 74 68 61 74 20 6d 61 63 72 6f   When that macro
1370: 20 69 73 20 66 61 6c 73 65 2c 0a 2a 2a 20 74 68   is false,.** th
1380: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1390: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
13a0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
13b0: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
13c0: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
13d0: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
13e0: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
13f0: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
1400: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
1410: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
1420: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
1430: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
1440: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
1450: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
1460: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
1470: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
1480: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
1490: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
14a0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
14b0: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68  e enabled..** Th
14c0: 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  e default behavi
14d0: 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65  or is for mutexe
14e0: 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e  s to be enabled.
14f0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1500: 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
1510: 64 20 62 79 20 61 20 70 72 6f 67 72 61 6d 20 74  d by a program t
1520: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
1530: 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20   the.** version 
1540: 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69  of SQLite that i
1550: 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61  t is linking aga
1560: 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65  inst was compile
1570: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65  d with.** the de
1580: 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66  sired setting of
1590: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
15a0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a  EADSAFE] macro..
15b0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
15c0: 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74  face only report
15d0: 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  s on the compile
15e0: 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74  -time mutex sett
15f0: 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53  ing.** of the [S
1600: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1610: 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69  ] flag.  If SQLi
1620: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
1630: 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48  ith.** SQLITE_TH
1640: 52 45 41 44 53 41 46 45 3d 31 20 74 68 65 6e 20  READSAFE=1 then 
1650: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62  mutexes are enab
1660: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62  led by default b
1670: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c  ut.** can be ful
1680: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20  ly or partially 
1690: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61  disabled using a
16a0: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
16b0: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77  3_config()].** w
16c0: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53  ith the verbs [S
16d0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
16e0: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c  GLETHREAD], [SQL
16f0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
1700: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b  THREAD],.** or [
1710: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
1720: 54 45 58 5d 2e 20 20 54 68 65 20 72 65 74 75 72  TEX].  The retur
1730: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
1740: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 0a 2a  function shows.*
1750: 2a 20 6f 6e 6c 79 20 74 68 65 20 64 65 66 61 75  * only the defau
1760: 6c 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  lt compile-time 
1770: 73 65 74 74 69 6e 67 2c 20 6e 6f 74 20 61 6e 79  setting, not any
1780: 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65   run-time change
1790: 73 0a 2a 2a 20 74 6f 20 74 68 61 74 20 73 65 74  s.** to that set
17a0: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ting..**.** INVA
17b0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
17c0: 31 30 31 30 31 7d 20 54 68 65 20 5b 73 71 6c 69  10101} The [sqli
17d0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
17e0: 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c  ] function shall
17f0: 20 72 65 74 75 72 6e 20 6e 6f 6e 7a 65 72 6f 20   return nonzero 
1800: 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  if.**          S
1810: 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c  QLite was compil
1820: 65 64 20 77 69 74 68 20 74 68 65 20 69 74 73 20  ed with the its 
1830: 6d 75 74 65 78 65 73 20 65 6e 61 62 6c 65 64 20  mutexes enabled 
1840: 62 79 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20  by default.**   
1850: 20 20 20 20 20 20 20 6f 72 20 7a 65 72 6f 20 69         or zero i
1860: 66 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d  f SQLite was com
1870: 70 69 6c 65 64 20 73 75 63 68 20 74 68 61 74 20  piled such that 
1880: 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 20  mutexes are.**  
1890: 20 20 20 20 20 20 20 20 70 65 72 6d 61 6e 65 6e          permanen
18a0: 74 6c 79 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  tly disabled..**
18b0: 0a 2a 2a 20 7b 48 31 30 31 30 32 7d 20 54 68 65  .** {H10102} The
18c0: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
18d0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
18e0: 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 66 75  threadsafe()] fu
18f0: 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  nction.**       
1900: 20 20 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68 61     shall not cha
1910: 6e 67 65 20 77 68 65 6e 20 6d 75 74 65 78 20 73  nge when mutex s
1920: 65 74 74 69 6e 67 20 61 72 65 20 6d 6f 64 69 66  etting are modif
1930: 69 65 64 20 61 74 0a 2a 2a 20 20 20 20 20 20 20  ied at.**       
1940: 20 20 20 72 75 6e 74 69 6d 65 20 75 73 69 6e 67     runtime using
1950: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
1960: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
1970: 65 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20  e and .**       
1980: 20 20 20 65 73 70 65 63 69 61 6c 6c 79 20 74 68     especially th
1990: 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
19a0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 0a  _SINGLETHREAD],.
19b0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
19c0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
19d0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
19e0: 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
19f0: 45 44 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ED],.**         
1a00: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
1a10: 46 49 47 5f 4d 55 54 45 58 5d 20 76 65 72 62 73  FIG_MUTEX] verbs
1a20: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1a30: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
1a40: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a50: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
1a60: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b  nection Handle {
1a70: 48 31 32 30 30 30 7d 20 3c 53 34 30 32 30 30 3e  H12000} <S40200>
1a80: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
1a90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1aa0: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
1ab0: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
1ac0: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
1ad0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
1ae0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
1af0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
1b00: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
1b10: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
1b20: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
1b30: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
1b40: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
1b50: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
1b60: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
1b70: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
1b80: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1b90: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
1ba0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
1bb0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
1bc0: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
1bd0: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
1be0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
1bf0: 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f  is its destructo
1c00: 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  r.  There are ma
1c10: 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61  ny other interfa
1c20: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
1c30: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1c40: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
1c50: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
1c60: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1c70: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1c80: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
1c90: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
1ca0: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
1cb0: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
1cc0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1cd0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
1ce0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
1cf0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
1d00: 65 67 65 72 20 54 79 70 65 73 20 7b 48 31 30 32  eger Types {H102
1d10: 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 2a 2a 20  00} <S10110>.** 
1d20: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
1d30: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
1d40: 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  nt64.**.** Becau
1d50: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63  se there is no c
1d60: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61  ross-platform wa
1d70: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d  y to specify 64-
1d80: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65  bit integer type
1d90: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c  s.** SQLite incl
1da0: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f  udes typedefs fo
1db0: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
1dc0: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
1dd0: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egers..**.** The
1de0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
1df0: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  nd sqlite3_uint6
1e00: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72  4 are the prefer
1e10: 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74  red type definit
1e20: 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  ions..** The sql
1e30: 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  ite_int64 and sq
1e40: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65  lite_uint64 type
1e50: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  s are supported 
1e60: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
1e70: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
1e80: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  nly..**.** INVAR
1e90: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
1ea0: 30 32 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  0201} The [sqlit
1eb0: 65 5f 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71  e_int64] and [sq
1ec0: 6c 69 74 65 33 5f 69 6e 74 36 34 5d 20 74 79 70  lite3_int64] typ
1ed0: 65 20 73 68 61 6c 6c 20 73 70 65 63 69 66 79 0a  e shall specify.
1ee0: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 36 34  **          a 64
1ef0: 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
1f00: 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32  ger..**.** {H102
1f10: 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f  02} The [sqlite_
1f20: 75 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c  uint64] and [sql
1f30: 69 74 65 33 5f 75 69 6e 74 36 34 5d 20 74 79 70  ite3_uint64] typ
1f40: 65 20 73 68 61 6c 6c 20 73 70 65 63 69 66 79 0a  e shall specify.
1f50: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 36 34  **          a 64
1f60: 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
1f70: 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66 64 65 66  teger..*/.#ifdef
1f80: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
1f90: 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c  PE.  typedef SQL
1fa0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
1fb0: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
1fc0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
1fd0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
1fe0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
1ff0: 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f  .#elif defined(_
2000: 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69  MSC_VER) || defi
2010: 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f  ned(__BORLANDC__
2020: 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e  ).  typedef __in
2030: 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  t64 sqlite_int64
2040: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
2050: 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c  gned __int64 sql
2060: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73  ite_uint64;.#els
2070: 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67  e.  typedef long
2080: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2090: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
20a0: 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20  f unsigned long 
20b0: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
20c0: 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74  uint64;.#endif.t
20d0: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e  ypedef sqlite_in
20e0: 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t64 sqlite3_int6
20f0: 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  4;.typedef sqlit
2100: 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e_uint64 sqlite3
2110: 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20  _uint64;../*.** 
2120: 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72  If compiling for
2130: 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61   a processor tha
2140: 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67  t lacks floating
2150: 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a   point support,.
2160: 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e  ** substitute in
2170: 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69  teger for floati
2180: 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66  ng-point..*/.#if
2190: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
21a0: 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23  FLOATING_POINT.#
21b0: 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73   define double s
21c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e  qlite3_int64.#en
21d0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
21e0: 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44  REF: Closing A D
21f0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2200: 6f 6e 20 7b 48 31 32 30 31 30 7d 20 3c 53 33 30  on {H12010} <S30
2210: 31 30 30 3e 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a  100><S40200>.**.
2220: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
2230: 69 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  is the destructo
2240: 72 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  r for the [sqlit
2250: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  e3] object..**.*
2260: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
2270: 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66  hould [sqlite3_f
2280: 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
2290: 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  ze] all [prepare
22a0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a  d statements].**
22b0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c   and [sqlite3_bl
22c0: 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65  ob_close | close
22d0: 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64  ] all [BLOB hand
22e0: 6c 65 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20  les] associated 
22f0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  with.** the [sql
2300: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69  ite3] object pri
2310: 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67  or to attempting
2320: 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62   to close the ob
2330: 6a 65 63 74 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  ject..** The [sq
2340: 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
2350: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  )] interface can
2360: 20 62 65 20 75 73 65 64 20 74 6f 20 6c 6f 63 61   be used to loca
2370: 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70 72 65 70 61  te all.** [prepa
2380: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
2390: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
23a0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
23b0: 65 63 74 69 6f 6e 5d 20 69 66 20 64 65 73 69 72  ection] if desir
23c0: 65 64 2e 0a 2a 2a 20 54 79 70 69 63 61 6c 20 63  ed..** Typical c
23d0: 6f 64 65 20 6d 69 67 68 74 20 6c 6f 6f 6b 20 6c  ode might look l
23e0: 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
23f0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
2400: 3e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  >.** sqlite3_stm
2410: 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a 20 77 68 69  t *pStmt;.** whi
2420: 6c 65 28 20 28 70 53 74 6d 74 20 3d 20 73 71 6c  le( (pStmt = sql
2430: 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 64  ite3_next_stmt(d
2440: 62 2c 20 30 29 29 21 3d 30 20 29 7b 0a 2a 2a 20  b, 0))!=0 ){.** 
2450: 26 6e 62 73 70 3b 20 20 20 73 71 6c 69 74 65 33  &nbsp;   sqlite3
2460: 5f 66 69 6e 61 6c 69 7a 65 28 70 53 74 6d 74 29  _finalize(pStmt)
2470: 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f 70 72 65 3e  ;.** }.** </pre>
2480: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
2490: 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
24a0: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
24b0: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
24c0: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
24d0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
24e0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
24f0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2500: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2510: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31  TS:.**.** {H1201
2520: 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  1} A successful 
2530: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2540: 5f 63 6c 6f 73 65 28 43 29 5d 20 73 68 61 6c 6c  _close(C)] shall
2550: 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20   destroy the.** 
2560: 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
2570: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
2580: 62 6a 65 63 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b  bject C..**.** {
2590: 48 31 32 30 31 32 7d 20 41 20 73 75 63 63 65 73  H12012} A succes
25a0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
25b0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
25c0: 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c  shall return SQL
25d0: 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ITE_OK..**.** {H
25e0: 31 32 30 31 33 7d 20 41 20 73 75 63 63 65 73 73  12013} A success
25f0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
2600: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73  ite3_close(C)] s
2610: 68 61 6c 6c 20 72 65 6c 65 61 73 65 20 61 6c 6c  hall release all
2620: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d  .**          mem
2630: 6f 72 79 20 61 6e 64 20 73 79 73 74 65 6d 20 72  ory and system r
2640: 65 73 6f 75 72 63 65 73 20 61 73 73 6f 63 69 61  esources associa
2650: 74 65 64 20 77 69 74 68 20 5b 64 61 74 61 62 61  ted with [databa
2660: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
2670: 2a 20 20 20 20 20 20 20 20 20 20 43 2e 0a 2a 2a  *          C..**
2680: 0a 2a 2a 20 7b 48 31 32 30 31 34 7d 20 41 20 63  .** {H12014} A c
2690: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
26a0: 63 6c 6f 73 65 28 43 29 5d 20 6f 6e 20 61 20 5b  close(C)] on a [
26b0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26c0: 69 6f 6e 5d 20 43 20 74 68 61 74 0a 2a 2a 20 20  ion] C that.**  
26d0: 20 20 20 20 20 20 20 20 68 61 73 20 6f 6e 65 20          has one 
26e0: 6f 72 20 6d 6f 72 65 20 6f 70 65 6e 20 5b 70 72  or more open [pr
26f0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2700: 73 5d 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69  s] shall fail wi
2710: 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  th.**          a
2720: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
2730: 65 72 72 6f 72 20 63 6f 64 65 2e 0a 2a 2a 0a 2a  error code..**.*
2740: 2a 20 7b 48 31 32 30 31 35 7d 20 41 20 63 61 6c  * {H12015} A cal
2750: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  l to [sqlite3_cl
2760: 6f 73 65 28 43 29 5d 20 77 68 65 72 65 20 43 20  ose(C)] where C 
2770: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2780: 72 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  r shall.**      
2790: 20 20 20 20 72 65 74 75 72 6e 20 53 51 4c 49 54      return SQLIT
27a0: 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  E_OK..**.** {H12
27b0: 30 31 39 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74  019} When [sqlit
27c0: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 69 73 20  e3_close(C)] is 
27d0: 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 5b 64 61  invoked on a [da
27e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
27f0: 6e 5d 20 43 0a 2a 2a 20 20 20 20 20 20 20 20 20  n] C.**         
2800: 20 74 68 61 74 20 68 61 73 20 61 20 70 65 6e 64   that has a pend
2810: 69 6e 67 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  ing transaction,
2820: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
2830: 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20   shall be.**    
2840: 20 20 20 20 20 20 72 6f 6c 6c 65 64 20 62 61 63        rolled bac
2850: 6b 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54  k..**.** ASSUMPT
2860: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  IONS:.**.** {A12
2870: 30 31 36 7d 20 54 68 65 20 43 20 70 61 72 61 6d  016} The C param
2880: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2890: 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75 73 74 20  _close(C)] must 
28a0: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
28b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69  .**          poi
28c0: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  nter or an [sqli
28d0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  te3] object poin
28e0: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ter obtained.** 
28f0: 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 5b 73           from [s
2900: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2910: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2920: 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
2930: 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
2940: 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20  _v2()], and not 
2950: 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65  previously close
2960: 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2970: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20  3_close(sqlite3 
2980: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
2990: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
29a0: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
29b0: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
29c0: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
29d0: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
29e0: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
29f0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
2a00: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
2a10: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
2a20: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
2a30: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
2a40: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
2a50: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2a60: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
2a70: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
2a80: 74 65 72 66 61 63 65 20 7b 48 31 32 31 30 30 7d  terface {H12100}
2a90: 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10000>.**.** 
2aa0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
2ab0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2ac0: 61 20 63 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79  a convenient way
2ad0: 20 6f 66 20 72 75 6e 6e 69 6e 67 20 6f 6e 65 20   of running one 
2ae0: 6f 72 20 6d 6f 72 65 0a 2a 2a 20 53 51 4c 20 73  or more.** SQL s
2af0: 74 61 74 65 6d 65 6e 74 73 20 77 69 74 68 6f 75  tatements withou
2b00: 74 20 68 61 76 69 6e 67 20 74 6f 20 77 72 69 74  t having to writ
2b10: 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64  e a lot of C cod
2b20: 65 2e 20 20 54 68 65 20 55 54 46 2d 38 20 65 6e  e.  The UTF-8 en
2b30: 63 6f 64 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  coded.** SQL sta
2b40: 74 65 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73  tements are pass
2b50: 65 64 20 69 6e 20 61 73 20 74 68 65 20 73 65 63  ed in as the sec
2b60: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
2b70: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2e   sqlite3_exec().
2b80: 0a 2a 2a 20 54 68 65 20 73 74 61 74 65 6d 65 6e  .** The statemen
2b90: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
2ba0: 20 6f 6e 65 20 62 79 20 6f 6e 65 20 75 6e 74 69   one by one unti
2bb0: 6c 20 65 69 74 68 65 72 20 61 6e 20 65 72 72 6f  l either an erro
2bc0: 72 20 6f 72 0a 2a 2a 20 61 6e 20 69 6e 74 65 72  r or.** an inter
2bd0: 72 75 70 74 20 69 73 20 65 6e 63 6f 75 6e 74 65  rupt is encounte
2be0: 72 65 64 2c 20 6f 72 20 75 6e 74 69 6c 20 74 68  red, or until th
2bf0: 65 79 20 61 72 65 20 61 6c 6c 20 64 6f 6e 65 2e  ey are all done.
2c00: 20 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65    The 3rd parame
2c10: 74 65 72 0a 2a 2a 20 69 73 20 61 6e 20 6f 70 74  ter.** is an opt
2c20: 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 74  ional callback t
2c30: 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hat is invoked o
2c40: 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77  nce for each row
2c50: 20 6f 66 20 61 6e 79 20 71 75 65 72 79 0a 2a 2a   of any query.**
2c60: 20 72 65 73 75 6c 74 73 20 70 72 6f 64 75 63 65   results produce
2c70: 64 20 62 79 20 74 68 65 20 53 51 4c 20 73 74 61  d by the SQL sta
2c80: 74 65 6d 65 6e 74 73 2e 20 20 54 68 65 20 35 74  tements.  The 5t
2c90: 68 20 70 61 72 61 6d 65 74 65 72 20 74 65 6c 6c  h parameter tell
2ca0: 73 20 77 68 65 72 65 0a 2a 2a 20 74 6f 20 77 72  s where.** to wr
2cb0: 69 74 65 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  ite any error me
2cc0: 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ssages..**.** Th
2cd0: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
2ce0: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
2cf0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
2d00: 6d 65 74 65 72 20 69 73 20 68 65 6c 64 0a 2a 2a  meter is held.**
2d10: 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   in memory obtai
2d20: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2d30: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f  3_malloc()].  To
2d40: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20   avoid a memory 
2d50: 6c 65 61 6b 2c 0a 2a 2a 20 74 68 65 20 63 61 6c  leak,.** the cal
2d60: 6c 69 6e 67 20 61 70 70 6c 69 63 61 74 69 6f 6e  ling application
2d70: 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 5b 73 71   should call [sq
2d80: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
2d90: 20 61 6e 79 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   any error.** me
2da0: 73 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 74  ssage returned t
2db0: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
2dc0: 61 72 61 6d 65 74 65 72 20 77 68 65 6e 20 69 74  arameter when it
2dd0: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
2de0: 69 6e 67 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  ing.** the error
2df0: 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
2e00: 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2e10: 6d 65 6e 74 20 69 6e 20 74 68 65 20 32 6e 64 20  ment in the 2nd 
2e20: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
2e30: 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74  L or an empty st
2e40: 72 69 6e 67 0a 2a 2a 20 6f 72 20 61 20 73 74 72  ring.** or a str
2e50: 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6f  ing containing o
2e60: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61  nly whitespace a
2e70: 6e 64 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  nd comments, the
2e80: 6e 20 6e 6f 20 53 51 4c 0a 2a 2a 20 73 74 61 74  n no SQL.** stat
2e90: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75  ements are evalu
2ea0: 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74  ated and the dat
2eb0: 61 62 61 73 65 20 69 73 20 6e 6f 74 20 63 68 61  abase is not cha
2ec0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nged..**.** The 
2ed0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
2ee0: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
2ef0: 65 6d 65 6e 74 65 64 20 69 6e 20 74 65 72 6d 73  emented in terms
2f00: 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
2f10: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
2f20: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
2f30: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69   and [sqlite3_fi
2f40: 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68  nalize()]..** Th
2f50: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
2f60: 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
2f70: 74 68 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74  thing to the dat
2f80: 61 62 61 73 65 20 74 68 61 74 20 63 61 6e 6e 6f  abase that canno
2f90: 74 20 62 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20  t be done.** by 
2fa0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2fb0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2fc0: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
2fd0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2fe0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
2ff0: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
3000: 31 30 31 7d 20 41 20 73 75 63 63 65 73 73 66 75  101} A successfu
3010: 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
3020: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c  [sqlite3_exec(D,
3030: 53 2c 43 2c 41 2c 45 29 5d 0a 2a 2a 20 20 20 20  S,C,A,E)].**    
3040: 20 20 20 20 20 20 73 68 61 6c 6c 20 73 65 71 75        shall sequ
3050: 65 6e 74 69 61 6c 6c 79 20 65 76 61 6c 75 61 74  entially evaluat
3060: 65 20 61 6c 6c 20 6f 66 20 74 68 65 20 55 54 46  e all of the UTF
3070: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 20  -8 encoded,.**  
3080: 20 20 20 20 20 20 20 20 73 65 6d 69 63 6f 6c 6f          semicolo
3090: 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20  n-separated SQL 
30a0: 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
30b0: 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
30c0: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  d.**          st
30d0: 72 69 6e 67 20 53 20 77 69 74 68 69 6e 20 74 68  ring S within th
30e0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
30f0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
3100: 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
3110: 7b 48 31 32 31 30 32 7d 20 49 66 20 74 68 65 20  {H12102} If the 
3120: 53 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  S parameter to [
3130: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53  sqlite3_exec(D,S
3140: 2c 43 2c 41 2c 45 29 5d 20 69 73 20 4e 55 4c 4c  ,C,A,E)] is NULL
3150: 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
3160: 20 20 74 68 65 20 61 63 74 69 6f 6e 73 20 6f 66    the actions of
3170: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 73   the interface s
3180: 68 61 6c 6c 20 62 65 20 74 68 65 20 73 61 6d 65  hall be the same
3190: 20 61 73 20 69 66 20 74 68 65 0a 2a 2a 20 20 20   as if the.**   
31a0: 20 20 20 20 20 20 20 53 20 70 61 72 61 6d 65 74         S paramet
31b0: 65 72 20 77 65 72 65 20 61 6e 20 65 6d 70 74 79  er were an empty
31c0: 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
31d0: 48 31 32 31 30 34 7d 20 54 68 65 20 72 65 74 75  H12104} The retu
31e0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  rn value of [sql
31f0: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61  ite3_exec()] sha
3200: 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 4f 4b  ll be [SQLITE_OK
3210: 5d 20 69 66 20 61 6c 6c 0a 2a 2a 20 20 20 20 20  ] if all.**     
3220: 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65       SQL stateme
3230: 6e 74 73 20 72 75 6e 20 73 75 63 63 65 73 73 66  nts run successf
3240: 75 6c 6c 79 20 61 6e 64 20 74 6f 20 63 6f 6d 70  ully and to comp
3250: 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48  letion..**.** {H
3260: 31 32 31 30 35 7d 20 54 68 65 20 72 65 74 75 72  12105} The retur
3270: 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  n value of [sqli
3280: 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c  te3_exec()] shal
3290: 6c 20 62 65 20 61 6e 20 61 70 70 72 6f 70 72 69  l be an appropri
32a0: 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ate.**          
32b0: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
32c0: 63 6f 64 65 5d 20 69 66 20 61 6e 79 20 53 51 4c  code] if any SQL
32d0: 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 73   statement fails
32e0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 37 7d  ..**.** {H12107}
32f0: 20 49 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   If one or more 
3300: 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  of the SQL state
3310: 6d 65 6e 74 73 20 68 61 6e 64 65 64 20 74 6f 20  ments handed to 
3320: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3330: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
3340: 75 72 6e 20 72 65 73 75 6c 74 73 20 61 6e 64 20  urn results and 
3350: 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
3360: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  r is not NULL, t
3370: 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
3380: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
3390: 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20  ction specified 
33a0: 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  by the 3rd param
33b0: 65 74 65 72 20 73 68 61 6c 6c 20 62 65 0a 2a 2a  eter shall be.**
33c0: 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 6b 65            invoke
33d0: 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
33e0: 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 0a 2a  row of result..*
33f0: 2a 0a 2a 2a 20 7b 48 31 32 31 31 30 7d 20 49 66  *.** {H12110} If
3400: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
3410: 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
3420: 20 76 61 6c 75 65 20 74 68 65 6e 20 5b 73 71 6c   value then [sql
3430: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20  ite3_exec()].** 
3440: 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 61           shall a
3450: 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
3460: 74 65 6d 65 6e 74 20 69 74 20 69 73 20 63 75 72  tement it is cur
3470: 72 65 6e 74 6c 79 20 65 76 61 6c 75 61 74 69 6e  rently evaluatin
3480: 67 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  g,.**          s
3490: 6b 69 70 20 61 6c 6c 20 73 75 62 73 65 71 75 65  kip all subseque
34a0: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  nt SQL statement
34b0: 73 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  s, and return [S
34c0: 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a  QLITE_ABORT]..**
34d0: 0a 2a 2a 20 7b 48 31 32 31 31 33 7d 20 54 68 65  .** {H12113} The
34e0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
34f0: 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
3500: 70 61 73 73 20 69 74 73 20 34 74 68 20 70 61 72  pass its 4th par
3510: 61 6d 65 74 65 72 20 74 68 72 6f 75 67 68 0a 2a  ameter through.*
3520: 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68  *          as th
3530: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
3540: 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  of the callback.
3550: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 36 7d 20  .**.** {H12116} 
3560: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  The [sqlite3_exe
3570: 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61  c()] routine sha
3580: 6c 6c 20 73 65 74 20 74 68 65 20 32 6e 64 20 70  ll set the 2nd p
3590: 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a  arameter of its.
35a0: 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
35b0: 62 61 63 6b 20 74 6f 20 62 65 20 74 68 65 20 6e  back to be the n
35c0: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
35d0: 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
35e0: 72 6f 77 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  row of.**       
35f0: 20 20 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a     result..**.**
3600: 20 7b 48 31 32 31 31 39 7d 20 54 68 65 20 5b 73   {H12119} The [s
3610: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
3620: 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74  outine shall set
3630: 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
3640: 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20  er of its.**    
3650: 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74        callback t
3660: 6f 20 62 65 20 61 6e 20 61 72 72 61 79 20 6f 66  o be an array of
3670: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3680: 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65  ings holding the
3690: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
36a0: 75 65 73 20 66 6f 72 20 65 61 63 68 20 63 6f 6c  ues for each col
36b0: 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
36c0: 6e 74 20 72 65 73 75 6c 74 20 73 65 74 20 72 6f  nt result set ro
36d0: 77 20 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  w as.**         
36e0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
36f0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
3700: 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ext()]..**.** {H
3710: 31 32 31 32 32 7d 20 54 68 65 20 5b 73 71 6c 69  12122} The [sqli
3720: 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74  te3_exec()] rout
3730: 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68  ine shall set th
3740: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
3750: 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20  of its.**       
3760: 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62     callback to b
3770: 65 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  e an array of po
3780: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3790: 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a  s holding the.**
37a0: 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 73 20            names 
37b0: 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
37c0: 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72  s as obtained fr
37d0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
37e0: 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a  mn_name()]..**.*
37f0: 2a 20 7b 48 31 32 31 32 35 7d 20 49 66 20 74 68  * {H12125} If th
3800: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
3810: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
3820: 28 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ()] is NULL then
3830: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
3840: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68  lite3_exec()] sh
3850: 61 6c 6c 20 73 69 6c 65 6e 74 6c 79 20 64 69 73  all silently dis
3860: 63 61 72 64 20 71 75 65 72 79 20 72 65 73 75 6c  card query resul
3870: 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33  ts..**.** {H1213
3880: 31 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  1} If an error o
3890: 63 63 75 72 73 20 77 68 69 6c 65 20 70 61 72 73  ccurs while pars
38a0: 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  ing or evaluatin
38b0: 67 20 61 6e 79 20 6f 66 20 74 68 65 20 53 51 4c  g any of the SQL
38c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61  .**          sta
38d0: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 53  tements in the S
38e0: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
38f0: 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c  qlite3_exec(D,S,
3900: 43 2c 41 2c 45 29 5d 20 61 6e 64 20 69 66 0a 2a  C,A,E)] and if.*
3910: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 45  *          the E
3920: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
3930: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 73 71  t NULL, then [sq
3940: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68  lite3_exec()] sh
3950: 61 6c 6c 20 73 74 6f 72 65 0a 2a 2a 20 20 20 20  all store.**    
3960: 20 20 20 20 20 20 69 6e 20 2a 45 20 61 6e 20 61        in *E an a
3970: 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
3980: 20 6d 65 73 73 61 67 65 20 77 72 69 74 74 65 6e   message written
3990: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
39a0: 61 69 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  ained.**        
39b0: 20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f    from [sqlite3_
39c0: 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a  malloc()]..**.**
39d0: 20 7b 48 31 32 31 33 34 7d 20 54 68 65 20 5b 73   {H12134} The [s
39e0: 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c  qlite3_exec(D,S,
39f0: 43 2c 41 2c 45 29 5d 20 72 6f 75 74 69 6e 65 20  C,A,E)] routine 
3a00: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 76 61  shall set the va
3a10: 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  lue of.**       
3a20: 20 20 20 2a 45 20 74 6f 20 4e 55 4c 4c 20 69 66     *E to NULL if
3a30: 20 45 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61   E is not NULL a
3a40: 6e 64 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  nd there are no 
3a50: 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  errors..**.** {H
3a60: 31 32 31 33 37 7d 20 54 68 65 20 5b 73 71 6c 69  12137} The [sqli
3a70: 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41  te3_exec(D,S,C,A
3a80: 2c 45 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68  ,E)] function sh
3a90: 61 6c 6c 20 73 65 74 20 74 68 65 20 5b 65 72 72  all set the [err
3aa0: 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 20 20 20 20  or code].**     
3ab0: 20 20 20 20 20 61 6e 64 20 6d 65 73 73 61 67 65       and message
3ac0: 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20   accessible via 
3ad0: 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
3ae0: 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
3af0: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
3b00: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
3b10: 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a  3_errmsg16()]..*
3b20: 2a 0a 2a 2a 20 7b 48 31 32 31 33 38 7d 20 49 66  *.** {H12138} If
3b30: 20 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72   the S parameter
3b40: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
3b50: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73  c(D,S,C,A,E)] is
3b60: 20 4e 55 4c 4c 20 6f 72 20 61 6e 0a 2a 2a 20 20   NULL or an.**  
3b70: 20 20 20 20 20 20 20 20 65 6d 70 74 79 20 73 74          empty st
3b80: 72 69 6e 67 20 6f 72 20 63 6f 6e 74 61 69 6e 73  ring or contains
3b90: 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74   nothing other t
3ba0: 68 61 6e 20 77 68 69 74 65 73 70 61 63 65 2c 20  han whitespace, 
3bb0: 63 6f 6d 6d 65 6e 74 73 2c 0a 2a 2a 20 20 20 20  comments,.**    
3bc0: 20 20 20 20 20 20 61 6e 64 2f 6f 72 20 73 65 6d        and/or sem
3bd0: 69 63 6f 6c 6f 6e 73 2c 20 74 68 65 6e 20 72 65  icolons, then re
3be0: 73 75 6c 74 73 20 6f 66 20 5b 73 71 6c 69 74 65  sults of [sqlite
3bf0: 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a  3_errcode()],.**
3c00: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
3c10: 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e  e3_errmsg()], an
3c20: 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d [sqlite3_errms
3c30: 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  g16()].**       
3c40: 20 20 20 73 68 61 6c 6c 20 72 65 73 65 74 20 74     shall reset t
3c50: 6f 20 69 6e 64 69 63 61 74 65 20 6e 6f 20 65 72  o indicate no er
3c60: 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55  rors..**.** ASSU
3c70: 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  MPTIONS:.**.** {
3c80: 41 31 32 31 34 31 7d 20 54 68 65 20 66 69 72 73  A12141} The firs
3c90: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
3ca0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3cb0: 6d 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64  must be an valid
3cc0: 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20 20 20   and open.**    
3cd0: 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
3ce0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  connection]..**.
3cf0: 2a 2a 20 7b 41 31 32 31 34 32 7d 20 54 68 65 20  ** {A12142} The 
3d00: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3d10: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  ion must not be 
3d20: 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20  closed while.** 
3d30: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
3d40: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e  3_exec()] is run
3d50: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  ning..**.** {A12
3d60: 31 34 33 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67  143} The calling
3d70: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
3d80: 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 72   use [sqlite3_fr
3d90: 65 65 28 29 5d 20 74 6f 20 66 72 65 65 0a 2a 2a  ee()] to free.**
3da0: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6d 65            the me
3db0: 6d 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73  mory that *errms
3dc0: 67 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  g is left pointi
3dd0: 6e 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65  ng at once the e
3de0: 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rror.**         
3df0: 20 6d 65 73 73 61 67 65 20 69 73 20 6e 6f 20 6c   message is no l
3e00: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
3e10: 0a 2a 2a 20 7b 41 31 32 31 34 35 7d 20 54 68 65  .** {A12145} The
3e20: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
3e30: 65 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70  ext in the 2nd p
3e40: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
3e50: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20  ite3_exec()].** 
3e60: 20 20 20 20 20 20 20 20 20 6d 75 73 74 20 72 65           must re
3e70: 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 77  main unchanged w
3e80: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 78  hile [sqlite3_ex
3e90: 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  ec()] is running
3ea0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
3eb0: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
3ec0: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
3ed0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ee0: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
3ef0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
3f00: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
3f10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3f20: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
3f30: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
3f40: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
3f50: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3f60: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
3f70: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
3f80: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
3f90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fa0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fb0: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
3fc0: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
3fd0: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
3fe0: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
3ff0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4000: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
4010: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
4020: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4030: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48   Result Codes {H
4040: 31 30 32 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a  10210} <S10700>.
4050: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
4060: 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f  ITE_OK {error co
4070: 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73  de} {error codes
4080: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
4090: 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65  result code} {re
40a0: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a  sult codes}.**.*
40b0: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75  * Many SQLite fu
40c0: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61  nctions return a
40d0: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74  n integer result
40e0: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73   code from the s
40f0: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65  et shown.** here
4100: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64   in order to ind
4110: 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f  icates success o
4120: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
4130: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
4140: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
4150: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
4160: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
4170: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c  * See also: [SQL
4180: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
4190: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
41a0: 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69   codes].*/.#defi
41b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20  ne SQLITE_OK    
41c0: 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75         0   /* Su
41d0: 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20  ccessful result 
41e0: 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d  */./* beginning-
41f0: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4200: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4210: 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20  _ERROR        1 
4220: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f    /* SQL error o
4230: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61  r missing databa
4240: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
4250: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20  LITE_INTERNAL   
4260: 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61    2   /* Interna
4270: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  l logic error in
4280: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69   SQLite */.#defi
4290: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20  ne SQLITE_PERM  
42a0: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63         3   /* Ac
42b0: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20  cess permission 
42c0: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
42d0: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20  e SQLITE_ABORT  
42e0: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c        4   /* Cal
42f0: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
4300: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74  quested an abort
4310: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4320: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20  TE_BUSY         
4330: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  5   /* The datab
4340: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b  ase file is lock
4350: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4360: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20  LITE_LOCKED     
4370: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65    6   /* A table
4380: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
4390: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
43a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d  efine SQLITE_NOM
43b0: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  EM        7   /*
43c0: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c   A malloc() fail
43d0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
43e0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20  LITE_READONLY   
43f0: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74    8   /* Attempt
4400: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64   to write a read
4410: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f  only database */
4420: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4430: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20  INTERRUPT    9  
4440: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65   /* Operation te
4450: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69  rminated by sqli
4460: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a  te3_interrupt()*
4470: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4480: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20  _IOERR       10 
4490: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f    /* Some kind o
44a0: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72  f disk I/O error
44b0: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65   occurred */.#de
44c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
44d0: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20  UPT     11   /* 
44e0: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73  The database dis
44f0: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f  k image is malfo
4500: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rmed */.#define 
4510: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
4520: 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55     12   /* NOT U
4530: 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65  SED. Table or re
4540: 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a  cord not found *
4550: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4560: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
4570: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
4580: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
4590: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
45a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45b0: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
45c0: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
45d0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
45e0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
45f0: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
4600: 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20      15   /* NOT 
4610: 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c  USED. Database l
4620: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72  ock protocol err
4630: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4640: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20  LITE_EMPTY      
4650: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   16   /* Databas
4660: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64  e is empty */.#d
4670: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
4680: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
4690: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
46a0: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
46b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
46c0: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
46d0: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
46e0: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
46f0: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
4700: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
4710: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
4720: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
4730: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
4740: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4750: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
4760: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
4770: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
4780: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4790: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
47a0: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
47b0: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
47c0: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
47d0: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
47e0: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
47f0: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4800: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4810: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4820: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
4830: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
4840: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4850: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
4860: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74  /* Auxiliary dat
4870: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72  abase format err
4880: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4890: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20  LITE_RANGE      
48a0: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72   25   /* 2nd par
48b0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
48c0: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61  3_bind out of ra
48d0: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge */.#define S
48e0: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20  QLITE_NOTADB    
48f0: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f    26   /* File o
4900: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f  pened that is no
4910: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
4920: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4930: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20  ITE_ROW         
4940: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  100  /* sqlite3_
4950: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68  step() has anoth
4960: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a  er row ready */.
4970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
4980: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20  ONE        101  
4990: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
49a0: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  ) has finished e
49b0: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65  xecuting */./* e
49c0: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  nd-of-error-code
49d0: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s */../*.** CAPI
49e0: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52  3REF: Extended R
49f0: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 30  esult Codes {H10
4a00: 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  220} <S10700>.**
4a10: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4a20: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d  nded error code}
4a30: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
4a40: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f   codes}.** KEYWO
4a50: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4a60: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74  esult code} {ext
4a70: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4a80: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
4a90: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4aa0: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4ab0: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4ac0: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4ad0: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
4ae0: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
4af0: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
4b00: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
4b10: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
4b20: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
4b30: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
4b40: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
4b50: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
4b60: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
4b70: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
4b80: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
4b90: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
4ba0: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4bb0: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4bc0: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4bd0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
4be0: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
4bf0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4c00: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4c10: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
4c20: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
4c30: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4c40: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4c50: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4c60: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
4c70: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
4c80: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4c90: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4ca0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4cb0: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4cc0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4cd0: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
4ce0: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a  des()] API..**.*
4cf0: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
4d00: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
4d10: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4d20: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a  e listed here..*
4d30: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74  * One may expect
4d40: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
4d50: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4d60: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70  odes will be exp
4d70: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65  and.** over time
4d80: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
4d90: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72   uses extended r
4da0: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75  esult codes shou
4db0: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20  ld expect.** to 
4dc0: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63  see new result c
4dd0: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  odes in future r
4de0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
4df0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  e..**.** The SQL
4e00: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f  ITE_OK result co
4e10: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65  de will never be
4e20: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77   extended.  It w
4e30: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  ill always.** be
4e40: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a   exactly zero..*
4e50: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
4e60: 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 33 7d 20  .**.** {H10223} 
4e70: 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d  The symbolic nam
4e80: 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65  e for an extende
4e90: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 73 68  d result code sh
4ea0: 61 6c 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  all contains.** 
4eb0: 20 20 20 20 20 20 20 20 20 61 20 72 65 6c 61 74           a relat
4ec0: 65 64 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c  ed primary resul
4ed0: 74 20 63 6f 64 65 20 61 73 20 61 20 70 72 65 66  t code as a pref
4ee0: 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32  ix..**.** {H1022
4ef0: 34 7d 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c  4} Primary resul
4f00: 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61  t code names sha
4f10: 6c 6c 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e  ll contain a sin
4f20: 67 6c 65 20 22 5f 22 20 63 68 61 72 61 63 74 65  gle "_" characte
4f30: 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 35  r..**.** {H10225
4f40: 7d 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c  } Extended resul
4f50: 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61  t code names sha
4f60: 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f  ll contain two o
4f70: 72 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61  r more "_" chara
4f80: 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  cters..**.** {H1
4f90: 30 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 69  0226} The numeri
4fa0: 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78  c value of an ex
4fb0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4fc0: 64 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e  de shall contain
4fd0: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
4fe0: 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f   numeric value o
4ff0: 66 20 69 74 73 20 63 6f 72 72 65 73 70 6f 6e 64  f its correspond
5000: 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65 73 75  ing primary resu
5010: 6c 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20 20 20  lt code in.**   
5020: 20 20 20 20 20 20 20 69 74 73 20 6c 65 61 73 74         its least
5030: 20 73 69 67 6e 69 66 69 63 61 6e 74 20 38 20 62   significant 8 b
5040: 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  its..*/.#define 
5050: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
5060: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  D              (
5070: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5080: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5090: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
50a0: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53  T_READ        (S
50b0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
50c0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
50d0: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45  LITE_IOERR_WRITE
50e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
50f0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
5100: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5110: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
5120: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5130: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c  ITE_IOERR | (4<<
5140: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5150: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59  TE_IOERR_DIR_FSY
5160: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
5170: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
5180: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5190: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
51a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51b0: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29  E_IOERR | (6<<8)
51c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51d0: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20  _IOERR_FSTAT    
51e0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
51f0: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
5200: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5210: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
5220: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5230: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a  IOERR | (8<<8)).
5240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5250: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20  OERR_RDLOCK     
5260: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5270: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
5280: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5290: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
52a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
52b0: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23  ERR | (10<<8)).#
52c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52d0: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20  ERR_BLOCKED     
52e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
52f0: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23  ERR | (11<<8)).#
5300: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5310: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ERR_NOMEM       
5320: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5330: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23  ERR | (12<<8)).#
5340: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5350: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20  ERR_ACCESS      
5360: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5370: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23  ERR | (13<<8)).#
5380: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5390: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45  ERR_CHECKRESERVE
53a0: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f  DLOCK (SQLITE_IO
53b0: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 0a  ERR | (14<<8))..
53c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
53d0: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
53e0: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b  pen Operations {
53f0: 48 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e  H10230} <H11120>
5400: 20 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H12700>.**.** 
5410: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
5420: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
5430: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20  r use in the.** 
5440: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
5450: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
5460: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
5470: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65  ce and.** in the
5480: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
5490: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
54a0: 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  od of the.** [sq
54b0: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
54c0: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
54d0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
54e0: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
54f0: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
5500: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
5510: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
5520: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
5530: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
5540: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5550: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
5560: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
5570: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
5580: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
5590: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
55a0: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
55b0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
55c0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
55d0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
55e0: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
55f0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
5600: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
5610: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
5620: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
5630: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
5640: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
5650: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
5660: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
5670: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
5680: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
5690: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
56a0: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
56b0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
56c0: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
56d0: 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  02000.#define SQ
56e0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
56f0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
5700: 30 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  04000.#define SQ
5710: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
5720: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
5730: 30 38 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  08000../*.** CAP
5740: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
5750: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48  aracteristics {H
5760: 31 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a  10240} <H11120>.
5770: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
5780: 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65  eCapabilities me
5790: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
57a0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
57b0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
57c0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
57d0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
57e0: 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20  of the these.** 
57f0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
5800: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
5810: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
5820: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
5830: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
5840: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
5850: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
5860: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
5870: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
5880: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5890: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
58a0: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
58b0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
58c0: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
58d0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
58e0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
58f0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
5900: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
5910: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
5920: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
5930: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
5940: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
5950: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
5960: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
5970: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
5980: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5990: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
59a0: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
59b0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
59c0: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
59d0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
59e0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
59f0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
5a00: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
5a10: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
5a20: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
5a30: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
5a40: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
5a50: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
5a60: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
5a70: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
5a80: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
5a90: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
5aa0: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
5ab0: 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  e()..*/.#define 
5ac0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5ad0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30  MIC          0x0
5ae0: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20  0000001.#define 
5af0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b00: 4d 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30  MIC512       0x0
5b10: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
5b20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b30: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30  MIC1K        0x0
5b40: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
5b50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b60: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30  MIC2K        0x0
5b70: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
5b80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b90: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30  MIC4K        0x0
5ba0: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
5bb0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5bc0: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30  MIC8K        0x0
5bd0: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
5be0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5bf0: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30  MIC16K       0x0
5c00: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
5c10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5c20: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30  MIC32K       0x0
5c30: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
5c40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5c50: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30  MIC64K       0x0
5c60: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
5c70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
5c80: 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30  E_APPEND     0x0
5c90: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
5ca0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
5cb0: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30  UENTIAL      0x0
5cc0: 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0000400../*.** C
5cd0: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
5ce0: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31  cking Levels {H1
5cf0: 30 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c  0250} <H11120> <
5d00: 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51  H11310>.**.** SQ
5d10: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66  Lite uses one of
5d20: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
5d30: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
5d40: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ond.** argument 
5d50: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65  to calls it make
5d60: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29  s to the xLock()
5d70: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d   and xUnlock() m
5d80: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20  ethods.** of an 
5d90: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
5da0: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ods] object..*/.
5db0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5dc0: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20  OCK_NONE        
5dd0: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
5de0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20  TE_LOCK_SHARED  
5df0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
5e00: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
5e10: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66  RVED      2.#def
5e20: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5e30: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a  PENDING       3.
5e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5e50: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20  OCK_EXCLUSIVE   
5e60: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    4../*.** CAPI3
5e70: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61  REF: Synchroniza
5e80: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20  tion Type Flags 
5e90: 7b 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30  {H10260} <H11120
5ea0: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  >.**.** When SQL
5eb0: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
5ec0: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
5ed0: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
5ee0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5ef0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
5f00: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
5f10: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
5f20: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
5f30: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
5f40: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
5f50: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
5f60: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
5f70: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
5f80: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
5f90: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
5fa0: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
5fb0: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
5fc0: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
5fd0: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
5fe0: 6c 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c 49  lushed. The SQLI
5ff0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66  TE_SYNC_NORMAL f
6000: 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  lag means.** to 
6010: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  use normal fsync
6020: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68  () semantics. Th
6030: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
6040: 4c 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a  LL flag means.**
6050: 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 2d 58   to use Mac OS-X
6060: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20   style fullsync 
6070: 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63  instead of fsync
6080: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
6090: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
60a0: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32  L        0x00002
60b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
60c0: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20  SYNC_FULL       
60d0: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69     0x00003.#defi
60e0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  ne SQLITE_SYNC_D
60f0: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30  ATAONLY      0x0
6100: 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0010../*.** CAPI
6110: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
6120: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
6130: 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 32  dle {H11110} <S2
6140: 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  0110>.**.** An [
6150: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
6160: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
6170: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
6180: 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66  the OS.** interf
6190: 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69  ace layer.  Indi
61a0: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
61b0: 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ace implementati
61c0: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
61d0: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
61e0: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
61f0: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
6200: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
6210: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
6220: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
6230: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
6240: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
6250: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6260: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
6270: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
6280: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
6290: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
62a0: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
62b0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
62c0: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
62d0: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
62e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
62f0: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
6300: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6310: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
6320: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
6330: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
6340: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6350: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
6360: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
6370: 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 32 30  s Object {H11120
6380: 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a  } <S20110>.**.**
6390: 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e   Every file open
63a0: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
63b0: 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65  e3_vfs] xOpen me
63c0: 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61  thod populates a
63d0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  n.** [sqlite3_fi
63e0: 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20  le] object (or, 
63f0: 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61  more commonly, a
6400: 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
6410: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
6420: 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20  e] object) with 
6430: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
6440: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
6450: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73   object..** This
6460: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
6470: 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64  the methods used
6480: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
6490: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ous operations.*
64a0: 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70  * against the op
64b0: 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e  en file represen
64c0: 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ted by the [sqli
64d0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
64e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
64f0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
6500: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
6510: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
6520: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
6530: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
6540: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
6550: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
6560: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
6570: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
6580: 73 20 61 20 4d 61 63 20 4f 53 2d 58 20 73 74 79  s a Mac OS-X sty
6590: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
65a0: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
65b0: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
65c0: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
65d0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
65e0: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
65f0: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
6600: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
6610: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
6620: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
6630: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
6640: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
6650: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
6660: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
6670: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
6680: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
6690: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
66a0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
66b0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
66c0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
66d0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
66e0: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
66f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
6700: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
6710: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
6720: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
6730: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
6740: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
6750: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
6760: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
6770: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
6780: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
6790: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
67a0: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
67b0: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
67c0: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
67d0: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
67e0: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
67f0: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
6800: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
6810: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
6820: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
6830: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
6840: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
6850: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
6860: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
6870: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
6880: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
6890: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
68a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
68b0: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
68c0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
68d0: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
68e0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
68f0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
6900: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
6910: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
6920: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
6930: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
6940: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
6950: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
6960: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
6970: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
6980: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
6990: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
69a0: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
69b0: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
69c0: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
69d0: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
69e0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
69f0: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
6a00: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
6a10: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
6a20: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
6a30: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
6a40: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
6a50: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
6a60: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
6a70: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
6a80: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
6a90: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
6aa0: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
6ab0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
6ac0: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
6ad0: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
6ae0: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
6af0: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
6b00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
6b10: 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66  KSTATE | list of
6b20: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
6b30: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
6b40: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
6b50: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
6b60: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
6b70: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
6b80: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
6b90: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
6ba0: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
6bb0: 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20  onflicts..**.** 
6bc0: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
6bd0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
6be0: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
6bf0: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
6c00: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
6c10: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
6c20: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
6c30: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
6c40: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
6c50: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
6c60: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
6c70: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
6c80: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
6c90: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
6ca0: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
6cb0: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
6cc0: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
6cd0: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
6ce0: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
6cf0: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
6d00: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
6d10: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
6d20: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6d30: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
6d40: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6d50: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
6d60: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6d70: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
6d80: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6d90: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
6da0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6db0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
6dc0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6dd0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
6de0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6df0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
6e00: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
6e10: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6e20: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
6e30: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
6e40: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
6e50: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
6e60: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75  QUENTIAL].** </u
6e70: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
6e80: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6e90: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6ea0: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
6eb0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
6ec0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6ed0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6ee0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
6ef0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
6f00: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
6f10: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
6f20: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
6f30: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
6f40: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
6f50: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
6f60: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
6f70: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6f80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6f90: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
6fa0: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
6fb0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
6fc0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
6fd0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
6fe0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
6ff0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
7000: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
7010: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
7020: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
7030: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
7040: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
7050: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
7060: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
7070: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
7080: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
7090: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
70a0: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
70b0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
70c0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
70d0: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f  hods sqlite3_io_
70e0: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
70f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7100: 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  ds {.  int iVers
7110: 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c  ion;.  int (*xCl
7120: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ose)(sqlite3_fil
7130: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65  e*);.  int (*xRe
7140: 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ad)(sqlite3_file
7150: 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  *, void*, int iA
7160: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
7170: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
7180: 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65  (*xWrite)(sqlite
7190: 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76  3_file*, const v
71a0: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
71b0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
71c0: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54  fst);.  int (*xT
71d0: 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33  runcate)(sqlite3
71e0: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
71f0: 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69  int64 size);.  i
7200: 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
7210: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66  te3_file*, int f
7220: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
7230: 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65  FileSize)(sqlite
7240: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
7250: 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a  _int64 *pSize);.
7260: 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73    int (*xLock)(s
7270: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7280: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c  t);.  int (*xUnl
7290: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
72a0: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
72b0: 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  (*xCheckReserved
72c0: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
72d0: 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  le*, int *pResOu
72e0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  t);.  int (*xFil
72f0: 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65  eControl)(sqlite
7300: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c  3_file*, int op,
7310: 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20   void *pArg);.  
7320: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a  int (*xSectorSiz
7330: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7340: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69  );.  int (*xDevi
7350: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
7360: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  s)(sqlite3_file*
7370: 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  );.  /* Addition
7380: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
7390: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
73a0: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
73b0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
73c0: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20  : Standard File 
73d0: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20  Control Opcodes 
73e0: 7b 48 31 31 33 31 30 7d 20 3c 53 33 30 38 30 30  {H11310} <S30800
73f0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  >.**.** These in
7400: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
7410: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
7420: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
7430: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
7440: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
7450: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
7460: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
7470: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7480: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
7490: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
74a0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
74b0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
74c0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
74d0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
74e0: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
74f0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7500: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
7510: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
7520: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
7530: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
7540: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
7550: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
7560: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
7570: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
7580: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
7590: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
75a0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
75b0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
75c0: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
75d0: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
75e0: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
75f0: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
7600: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e  g testing and on
7610: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  ly needs to be s
7620: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51  upported when SQ
7630: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20  LITE_TEST.** is 
7640: 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
7650: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
7660: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f  _SIZE_HINT] opco
7670: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51  de is used by SQ
7680: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65  Lite to give the
7690: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20   VFS.** layer a 
76a0: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67  hint of how larg
76b0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
76c0: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f  ile will grow to
76d0: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a   be during the.*
76e0: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  * current transa
76f0: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e  ction.  This hin
7700: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  t is not guarant
7710: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61  eed to be accura
7720: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20  te but it.** is 
7730: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68  often close.  Th
7740: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53  e underlying VFS
7750: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f   might choose to
7760: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74   preallocate dat
7770: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70  abase.** file sp
7780: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69  ace based on thi
7790: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20  s hint in order 
77a0: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74  to help writes t
77b0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
77c0: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65  * file run faste
77d0: 72 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  r..*/.#define SQ
77e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
77f0: 54 41 54 45 20 20 20 20 20 20 20 20 31 0a 23 64  TATE        1.#d
7800: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
7810: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20  TL_SIZE_HINT    
7820: 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      2../*.** CAP
7830: 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e  I3REF: Mutex Han
7840: 64 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 32  dle {H17110} <S2
7850: 30 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0130>.**.** The 
7860: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74  mutex module wit
7870: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e  hin SQLite defin
7880: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  es [sqlite3_mute
7890: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61  x] to be an.** a
78a0: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72  bstract type for
78b0: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e   a mutex object.
78c0: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
78d0: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a  e never looks.**
78e0: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   at the internal
78f0: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
7900: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d  of an [sqlite3_m
7910: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a  utex].  It only.
7920: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f  ** deals with po
7930: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73  inters to the [s
7940: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62  qlite3_mutex] ob
7950: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65  ject..**.** Mute
7960: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20  xes are created 
7970: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
7980: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  utex_alloc()]..*
7990: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
79a0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73   sqlite3_mutex s
79b0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f  qlite3_mutex;../
79c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
79d0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65  S Interface Obje
79e0: 63 74 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 30  ct {H11140} <S20
79f0: 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  100>.**.** An in
7a00: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71  stance of the sq
7a10: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
7a20: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
7a30: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a  erface between.*
7a40: 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * the SQLite cor
7a50: 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c  e and the underl
7a60: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
7a70: 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73  ystem.  The "vfs
7a80: 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65  ".** in the name
7a90: 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73   of the object s
7aa0: 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75  tands for "virtu
7ab0: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e  al file system".
7ac0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  .**.** The value
7ad0: 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   of the iVersion
7ae0: 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61   field is initia
7af0: 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65  lly 1 but may be
7b00: 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75   larger in.** fu
7b10: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
7b20: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69   SQLite.  Additi
7b30: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20  onal fields may 
7b40: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74  be appended to t
7b50: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68  his.** object wh
7b60: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  en the iVersion 
7b70: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73  value is increas
7b80: 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  ed.  Note that t
7b90: 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  he structure.** 
7ba0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
7bb0: 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65  fs object change
7bc0: 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63  s in the transac
7bd0: 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  tion between.** 
7be0: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
7bf0: 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61  .5.9 and 3.6.0 a
7c00: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73  nd yet the iVers
7c10: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f  ion field was no
7c20: 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a  t.** modified..*
7c30: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c  *.** The szOsFil
7c40: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73  e field is the s
7c50: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c  ize of the subcl
7c60: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66  assed [sqlite3_f
7c70: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ile].** structur
7c80: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56  e used by this V
7c90: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20  FS.  mxPathname 
7ca0: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c  is the maximum l
7cb0: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61  ength of.** a pa
7cc0: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56  thname in this V
7cd0: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  FS..**.** Regist
7ce0: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73  ered sqlite3_vfs
7cf0: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70   objects are kep
7d00: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69  t on a linked li
7d10: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20  st formed by.** 
7d20: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
7d30: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  r.  The [sqlite3
7d40: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
7d50: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
7d60: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
7d70: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  )] interfaces ma
7d80: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a  nage this list.*
7d90: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61  * in a thread-sa
7da0: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71  fe way.  The [sq
7db0: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
7dc0: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73  ] interface.** s
7dd0: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74  earches the list
7de0: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61  .  Neither the a
7df0: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
7e00: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69  nor the VFS.** i
7e10: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
7e20: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65  ould use the pNe
7e30: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  xt pointer..**.*
7e40: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c  * The pNext fiel
7e50: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69  d is the only fi
7e60: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  eld in the sqlit
7e70: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74  e3_vfs.** struct
7e80: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ure that SQLite 
7e90: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79  will ever modify
7ea0: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f  .  SQLite will o
7eb0: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72  nly access.** or
7ec0: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65   modify this fie
7ed0: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67  ld while holding
7ee0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74   a particular st
7ef0: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54  atic mutex..** T
7f00: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
7f10: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69  hould never modi
7f20: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68  fy anything with
7f30: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
7f40: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63  fs.** object onc
7f50: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73  e the object has
7f60: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64   been registered
7f70: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d  ..**.** The zNam
7f80: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68  e field holds th
7f90: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46  e name of the VF
7fa0: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e  S module.  The n
7fb0: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75  ame must.** be u
7fc0: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c  nique across all
7fd0: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a   VFS modules..**
7fe0: 0a 2a 2a 20 7b 48 31 31 31 34 31 7d 20 53 51 4c  .** {H11141} SQL
7ff0: 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74  ite will guarant
8000: 65 65 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  ee that the zFil
8010: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
8020: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
8030: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
8040: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
8050: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
8060: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 2e  xFullPathname().
8070: 20 20 53 51 4c 69 74 65 20 66 75 72 74 68 65 72    SQLite further
8080: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
8090: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
80a0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
80b0: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
80c0: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
80d0: 63 61 6c 6c 65 64 2e 20 7b 45 4e 44 7d 20 20 42  called. {END}  B
80e0: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72  ecause of the pr
80f0: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 73 65 2c  evious sentense,
8100: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
8110: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c  _file] can safel
8120: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65  y store a pointe
8130: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65  r to the.** file
8140: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73  name if it needs
8150: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65   to remember the
8160: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f   filename for so
8170: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66  me reason..** If
8180: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
8190: 61 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65  arameter is xOpe
81a0: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n is a NULL poin
81b0: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a  ter then xOpen.*
81c0: 2a 20 6d 75 73 74 20 69 6e 76 69 74 65 20 69 74  * must invite it
81d0: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20  s own temporary 
81e0: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c  name for the fil
81f0: 65 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65  e.  Whenever the
8200: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
8210: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
8220: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
8230: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
8240: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
8250: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
8260: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
8270: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
8280: 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 32 7d 20 54  **.** {H11142} T
8290: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
82a0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
82b0: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
82c0: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
82d0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
82e0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
82f0: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
8300: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
8310: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
8320: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
8330: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
8340: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
8350: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
8360: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
8370: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 7b 45  OPEN_CREATE]. {E
8380: 4e 44 7d 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ND}.** If xOpen(
8390: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
83a0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
83b0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
83c0: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
83d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
83e0: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
83f0: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
8400: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
8410: 2a 2a 20 7b 48 31 31 31 34 33 7d 20 53 51 4c 69  ** {H11143} SQLi
8420: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64  te will also add
8430: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
8440: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
8450: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61  he xOpen().** ca
8460: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ll, depending on
8470: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e   the object bein
8480: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20  g opened:.**.** 
8490: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  <ul>.** <li>  [S
84a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
84b0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
84c0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
84d0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
84e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
84f0: 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  MP_DB].** <li>  
8500: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
8510: 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  P_JOURNAL].** <l
8520: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
8530: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a  _TRANSIENT_DB].*
8540: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8550: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d  OPEN_SUBJOURNAL]
8560: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
8570: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
8580: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20  URNAL].** </ul> 
8590: 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  {END}.**.** The 
85a0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
85b0: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
85c0: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
85d0: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
85e0: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
85f0: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
8600: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
8610: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
8620: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
8630: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
8640: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
8650: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
8660: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
8670: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
8680: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
8690: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
86a0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
86b0: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
86c0: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
86d0: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
86e0: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
86f0: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
8700: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
8710: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
8720: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
8730: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
8740: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
8750: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
8760: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
8770: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
8780: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
8790: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
87a0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
87b0: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
87c0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
87d0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
87e0: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
87f0: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
8800: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8810: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
8820: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
8830: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
8840: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
8850: 0a 2a 2a 20 7b 48 31 31 31 34 35 7d 20 54 68 65  .** {H11145} The
8860: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
8870: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61  LETEONCLOSE] fla
8880: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
8890: 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65   should be.** de
88a0: 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73  leted when it is
88b0: 20 63 6c 6f 73 65 64 2e 20 20 7b 48 31 31 31 34   closed.  {H1114
88c0: 36 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  6} The [SQLITE_O
88d0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
88e0: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
88f0: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61  t for TEMP  data
8900: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20  bases, journals 
8910: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e  and for subjourn
8920: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31  als..**.** {H111
8930: 34 37 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  47} The [SQLITE_
8940: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20  OPEN_EXCLUSIVE] 
8950: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
8960: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
8970: 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78 63 6c  ened.** for excl
8980: 75 73 69 76 65 20 61 63 63 65 73 73 2e 20 20 54  usive access.  T
8990: 68 69 73 20 66 6c 61 67 20 69 73 20 73 65 74 20  his flag is set 
89a0: 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20 65 78  for all files ex
89b0: 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68 65 20  cept.** for the 
89c0: 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
89d0: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34  le..**.** {H1114
89e0: 38 7d 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  8} At least szOs
89f0: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
8a00: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
8a10: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
8a20: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
8a30: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
8a40: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
8a50: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
8a60: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
8a70: 7b 45 4e 44 7d 20 20 54 68 65 20 78 4f 70 65 6e  {END}  The xOpen
8a80: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74   method does not
8a90: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f   have to.** allo
8aa0: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75  cate the structu
8ab0: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75  re; it should ju
8ac0: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a  st fill it in..*
8ad0: 2a 0a 2a 2a 20 7b 48 31 31 31 34 39 7d 20 54 68  *.** {H11149} Th
8ae0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
8af0: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
8b00: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
8b10: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
8b20: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
8b30: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
8b40: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
8b50: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
8b60: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
8b70: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
8b80: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
8b90: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
8ba0: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
8bb0: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
8bc0: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
8bd0: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 7b 45 4e  st readable. {EN
8be0: 44 7d 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  D}  The file can
8bf0: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
8c00: 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 35  ry..**.** {H1115
8c10: 30 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  0} SQLite will a
8c20: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61  lways allocate a
8c30: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61  t least mxPathna
8c40: 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74  me+1 bytes for t
8c50: 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66  he.** output buf
8c60: 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  fer xFullPathnam
8c70: 65 2e 20 7b 48 31 31 31 35 31 7d 20 54 68 65 20  e. {H11151} The 
8c80: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
8c90: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
8ca0: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
8cb0: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
8cc0: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
8cd0: 73 2e 20 7b 45 4e 44 7d 20 20 49 66 20 74 68 65  s. {END}  If the
8ce0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
8cf0: 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65  * is not large e
8d00: 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43  nough, [SQLITE_C
8d10: 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20  ANTOPEN] should 
8d20: 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e  be returned. Sin
8d30: 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61  ce this is.** ha
8d40: 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c  ndled as a fatal
8d50: 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65   error by SQLite
8d60: 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61  , vfs implementa
8d70: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64  tions should end
8d80: 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76  eavor.** to prev
8d90: 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74  ent this by sett
8da0: 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74  ing mxPathname t
8db0: 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79  o a sufficiently
8dc0: 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a   large value..**
8dd0: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
8de0: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c  ess(), xSleep(),
8df0: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d   and xCurrentTim
8e00: 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
8e10: 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  * are not strict
8e20: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
8e30: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
8e40: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
8e50: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
8e60: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
8e70: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
8e80: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
8e90: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
8ea0: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
8eb0: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
8ec0: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
8ed0: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
8ee0: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
8ef0: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
8f00: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
8f10: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
8f20: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
8f30: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
8f40: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
8f50: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
8f60: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
8f70: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
8f80: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
8f90: 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20  nds given.  The 
8fa0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a  xCurrentTime().*
8fb0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
8fc0: 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75   a Julian Day Nu
8fd0: 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72  mber for the cur
8fe0: 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69  rent date and ti
8ff0: 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  me..*/.typedef s
9000: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
9010: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73  s sqlite3_vfs;.s
9020: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
9030: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
9040: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
9050: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
9060: 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20  ion number */.  
9070: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
9080: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
9090: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
90a0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
90b0: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
90c0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
90d0: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
90e0: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
90f0: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
9100: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
9110: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
9120: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
9130: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
9140: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
9150: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
9160: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
9170: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
9180: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
9190: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
91a0: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
91b0: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
91c0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
91d0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
91e0: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
91f0: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
9200: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
9210: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
9220: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
9230: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
9240: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
9250: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
9260: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
9270: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
9280: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
9290: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
92a0: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
92b0: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
92c0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
92d0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
92e0: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
92f0: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
9300: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9310: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
9320: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
9330: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
9340: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
9350: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
9360: 67 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  g);.  void *(*xD
9370: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
9380: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
9390: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a  char *zSymbol);.
93a0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
93b0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
93c0: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
93d0: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
93e0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
93f0: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
9400: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
9410: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
9420: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
9430: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
9440: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
9450: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
9460: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
9470: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
9480: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
9490: 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66  r *);.  /* New f
94a0: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
94b0: 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20  ended in figure 
94c0: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69  versions.  The i
94d0: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c  Version.  ** val
94e0: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e  ue will incremen
94f0: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20  t whenever this 
9500: 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a  happens. */.};..
9510: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9520: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
9530: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
9540: 20 7b 48 31 31 31 39 30 7d 20 3c 48 31 31 31 34   {H11190} <H1114
9550: 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 39 31  0>.**.** {H11191
9560: 7d 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  } These integer 
9570: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
9580: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
9590: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
95a0: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
95b0: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
95c0: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
95d0: 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20 64 65  . {END}  They de
95e0: 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
95f0: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
9600: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
9610: 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e  method is lookin
9620: 67 20 66 6f 72 2e 0a 2a 2a 20 7b 48 31 31 31 39  g for..** {H1119
9630: 32 7d 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  2} With SQLITE_A
9640: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
9650: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
9660: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
9670: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
9680: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 7b 48  le exists..** {H
9690: 31 31 31 39 33 7d 20 57 69 74 68 20 53 51 4c 49  11193} With SQLI
96a0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
96b0: 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73  ITE, the xAccess
96c0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
96d0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
96e0: 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61 64 61  le is both reada
96f0: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
9700: 2e 0a 2a 2a 20 7b 48 31 31 31 39 34 7d 20 57 69  ..** {H11194} Wi
9710: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
9720: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
9730: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
9740: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
9750: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
9760: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
9770: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
9780: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
9790: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
97a0: 44 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65  DWRITE 1.#define
97b0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
97c0: 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a  EAD      2../*.*
97d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
97e0: 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
97f0: 65 20 4c 69 62 72 61 72 79 20 7b 48 31 30 31 33  e Library {H1013
9800: 30 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 31  0} <S20000><S301
9810: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
9820: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9830: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
9840: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
9850: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
9860: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
9870: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
9880: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
9890: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
98a0: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
98b0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
98c0: 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20  lize()..**.** A 
98d0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
98e0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
98f0: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
9900: 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20  all if it is.** 
9910: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
9920: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9930: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64  e() is invoked d
9940: 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
9950: 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f  me of.** the pro
9960: 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69  cess, or if it i
9970: 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  s the first time
9980: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9990: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
99a0: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
99b0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
99c0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c  shutdown().  Onl
99d0: 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  y an effective c
99e0: 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  all.** of sqlite
99f0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
9a00: 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69  oes any initiali
9a10: 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68  zation.  All oth
9a20: 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20  er calls.** are 
9a30: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
9a40: 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68  .**.** Among oth
9a50: 65 72 20 74 68 69 6e 67 73 2c 20 73 71 6c 69 74  er things, sqlit
9a60: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9a70: 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20  shall invoke.** 
9a80: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
9a90: 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 73  ).  Similarly, s
9aa0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
9ab0: 29 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e 76 6f 6b  ).** shall invok
9ac0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
9ad0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ()..**.** The sq
9ae0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9af0: 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
9b00: 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20  ns SQLITE_OK on 
9b10: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49 66 20 66  success..** If f
9b20: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20  or some reason, 
9b30: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9b40: 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  ze() is unable t
9b50: 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20  o initialize.** 
9b60: 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72  the library (per
9b70: 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c  haps it is unabl
9b80: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20  e to allocate a 
9b90: 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20  needed resource 
9ba0: 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74  such.** as a mut
9bb0: 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61  ex) it returns a
9bc0: 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
9bd0: 74 68 65 72 20 74 68 61 6e 20 53 51 4c 49 54 45  ther than SQLITE
9be0: 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  _OK..**.** The s
9bf0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9c00: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
9c10: 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
9c20: 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
9c30: 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
9c40: 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
9c50: 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
9c60: 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
9c70: 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
9c80: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9c90: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
9ca0: 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
9cb0: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
9cc0: 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
9cd0: 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
9ce0: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
9cf0: 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
9d00: 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
9d10: 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
9d20: 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
9d30: 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
9d40: 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
9d50: 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 48  d.** already.  H
9d60: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
9d70: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
9d80: 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  th the SQLITE_OM
9d90: 49 54 5f 41 55 54 4f 49 4e 49 54 0a 2a 2a 20 63  IT_AUTOINIT.** c
9da0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
9db0: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74  on, then the aut
9dc0: 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20  omatic calls to 
9dd0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9de0: 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74  ze().** are omit
9df0: 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c  ted and the appl
9e00: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c  ication must cal
9e10: 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  l sqlite3_initia
9e20: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a  lize() directly.
9e30: 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ** prior to usin
9e40: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
9e50: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
9e60: 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61  or maximum porta
9e70: 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73  bility,.** it is
9e80: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
9e90: 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  t applications a
9ea0: 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c  lways invoke sql
9eb0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9ec0: 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72  ).** directly pr
9ed0: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
9ee0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
9ef0: 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65  terface.  Future
9f00: 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20   releases.** of 
9f10: 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69  SQLite may requi
9f20: 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68  re this.  In oth
9f30: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65  er words, the be
9f40: 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64  havior exhibited
9f50: 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
9f60: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
9f70: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54   SQLITE_OMIT_AUT
9f80: 4f 49 4e 49 54 20 6d 69 67 68 74 20 62 65 63 6f  OINIT might beco
9f90: 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c  me the.** defaul
9fa0: 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f  t behavior in so
9fb0: 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
9fc0: 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  e of SQLite..**.
9fd0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
9fe0: 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65  s_init() routine
9ff0: 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d   does operating-
a000: 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a  system specific.
a010: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ** initializatio
a020: 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  n of the SQLite 
a030: 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71  library.  The sq
a040: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
a050: 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73  * routine undoes
a060: 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73   the effect of s
a070: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a080: 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73  .  Typical tasks
a090: 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79  .** performed by
a0a0: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
a0b0: 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69  include allocati
a0c0: 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69  on or deallocati
a0d0: 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20  on.** of static 
a0e0: 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69  resources, initi
a0f0: 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f  alization of glo
a100: 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a  bal variables,.*
a110: 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64  * setting up a d
a120: 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
a130: 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20  vfs] module, or 
a140: 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20  setting up.** a 
a150: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
a160: 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c  ation using [sql
a170: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a  ite3_config()]..
a180: 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
a190: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
a1a0: 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  er invoke either
a1b0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
a1c0: 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
a1d0: 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74  _os_end() direct
a1e0: 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  ly.  The applica
a1f0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79  tion should only
a200: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
a210: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
a220: 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74  and sqlite3_shut
a230: 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c  down().  The sql
a240: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
a250: 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63  * interface is c
a260: 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61  alled automatica
a270: 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69  lly by sqlite3_i
a280: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a  nitialize() and.
a290: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ** sqlite3_os_en
a2a0: 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79  d() is called by
a2b0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
a2c0: 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74  n().  Appropriat
a2d0: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
a2e0: 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33  ions for sqlite3
a2f0: 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
a300: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
a310: 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74  ** are built int
a320: 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74  o SQLite when it
a330: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72   is compiled for
a340: 20 75 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c 20   unix, windows, 
a350: 6f 72 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e  or os/2..** When
a360: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
a370: 20 70 6c 61 74 66 6f 72 6d 73 20 28 75 73 69 6e   platforms (usin
a380: 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 53 5f  g the SQLITE_OS_
a390: 4f 54 48 45 52 3d 31 20 63 6f 6d 70 69 6c 65 2d  OTHER=1 compile-
a3a0: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
a3b0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
a3c0: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
a3d0: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
a3e0: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
a3f0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
a400: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
a410: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
a420: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
a430: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
a440: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
a450: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
a460: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
a470: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
a480: 4b 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  K on success and
a490: 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
a4a0: 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
a4b0: 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
a4c0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a4d0: 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
a4e0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a4f0: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
a500: 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
a510: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
a520: 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
a530: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
a540: 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
a550: 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48 31 30  ite Library {H10
a560: 31 34 35 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33  145} <S20000><S3
a570: 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0200>.** EXPERIM
a580: 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ENTAL.**.** The 
a590: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a5a0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
a5b0: 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
a5c0: 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
a5d0: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
a5e0: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
a5f0: 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
a600: 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
a610: 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
a620: 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
a630: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
a640: 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
a650: 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
a660: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
a670: 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
a680: 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
a690: 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
a6a0: 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
a6b0: 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
a6c0: 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
a6d0: 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
a6e0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
a6f0: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
a700: 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
a710: 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c  dsafe.  The appl
a720: 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
a730: 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f  insure that no o
a740: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
a750: 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b  rfaces are invok
a760: 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74  ed by other.** t
a770: 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c  hreads while sql
a780: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
a790: 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68   running.  Furth
a7a0: 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f  ermore, sqlite3_
a7b0: 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20  config().** may 
a7c0: 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
a7d0: 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
a7e0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
a7f0: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
a800: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
a810: 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
a820: 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
a830: 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f  utdown()]..** No
a840: 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61  te, however, tha
a850: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  t sqlite3_config
a860: 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  () can be called
a870: 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a   as part of the.
a880: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
a890: 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74  n of an applicat
a8a0: 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c  ion-defined [sql
a8b0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e  ite3_os_init()].
a8c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
a8d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
a8e0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
a8f0: 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   an integer.** [
a900: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
a910: 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e  NGLETHREAD | con
a920: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
a930: 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  n] that determin
a940: 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65  es.** what prope
a950: 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73  rty of SQLite is
a960: 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65   to be configure
a970: 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61  d.  Subsequent a
a980: 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79  rguments.** vary
a990: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
a9a0: 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
a9b0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20  _SINGLETHREAD | 
a9c0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
a9d0: 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
a9e0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
a9f0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f 6e  **.** When a con
aa00: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
aa10: 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
aa20: 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
aa30: 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a  ns SQLITE_OK..**
aa40: 20 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69   If the option i
aa50: 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c  s unknown or SQL
aa60: 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
aa70: 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a   set the option.
aa80: 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  ** then this rou
aa90: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
aaa0: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
aab0: 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ode]..*/.int sql
aac0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
aad0: 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
aae0: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
aaf0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
ab00: 63 74 69 6f 6e 73 20 20 7b 48 31 30 31 38 30 7d  ctions  {H10180}
ab10: 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50   <S20000>.** EXP
ab20: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
ab30: 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
ab40: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
ab50: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
ab60: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
ab70: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
ab80: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
ab90: 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
aba0: 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
abb0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
abc0: 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
abd0: 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
abe0: 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
abf0: 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
ac00: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
ac10: 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
ac20: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20  irst argument). 
ac30: 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
ac40: 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
ac50: 72 66 61 63 65 20 63 61 6e 20 6f 6e 6c 79 20 62  rface can only b
ac60: 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61 74 65  e used immediate
ac70: 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68 65 20  ly after.** the 
ac80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
ac90: 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 20 75  ion is created u
aca0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70  sing [sqlite3_op
acb0: 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  en()],.** [sqlit
acc0: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72  e3_open16()], or
acd0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
ace0: 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  2()].  .**.** Th
acf0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
ad00: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  t to sqlite3_db_
ad10: 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20  config(D,V,...) 
ad20: 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e 66 69   is the.** confi
ad30: 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20 2d 20  guration verb - 
ad40: 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
ad50: 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77  that indicates w
ad60: 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20 6f 66  hat.** aspect of
ad70: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
ad80: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
ad90: 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
ada0: 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68 6f 69  ** The only choi
adb0: 63 65 20 66 6f 72 20 74 68 69 73 20 76 61 6c 75  ce for this valu
adc0: 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 42 43  e is [SQLITE_DBC
add0: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
ade0: 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 20 61  ..** New verbs a
adf0: 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65 20  re likely to be 
ae00: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
ae10: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
ae20: 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  te..** Additiona
ae30: 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65 70 65  l arguments depe
ae40: 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62 2e 0a  nd on the verb..
ae50: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
ae60: 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33  b_config(sqlite3
ae70: 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  *, int op, ...);
ae80: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
ae90: 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
aea0: 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31  ion Routines {H1
aeb0: 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e 0a 2a  0155} <S20120>.*
aec0: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
aed0: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
aee0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
aef0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
af00: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
af10: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
af20: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
af30: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
af40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
af50: 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
af60: 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
af70: 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
af80: 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
af90: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
afa0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
afb0: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
afc0: 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
afd0: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
afe0: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
aff0: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
b000: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
b010: 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 61 74  LLOC].  By creat
b020: 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
b030: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
b040: 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
b050: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
b060: 66 69 67 28 29 5d 20 64 75 72 69 6e 67 20 63 6f  fig()] during co
b070: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 0a  nfiguration, an.
b080: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  ** application c
b090: 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
b0a0: 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
b0b0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
b0c0: 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 51 4c  ystem.** for SQL
b0d0: 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
b0e0: 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
b0f0: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
b100: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
b110: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
b120: 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  h a built-in mem
b130: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
b140: 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65 63 74  at is.** perfect
b150: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
b160: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
b170: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
b180: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
b190: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
b1a0: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
b1b0: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
b1c0: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
b1d0: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
b1e0: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
b1f0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
b200: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
b210: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
b220: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
b230: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
b240: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
b250: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
b260: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
b270: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
b280: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
b290: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
b2a0: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
b2b0: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
b2c0: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
b2d0: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
b2e0: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
b2f0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
b300: 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61 6e 64  lloc, xFree, and
b310: 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64   xRealloc method
b320: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
b330: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
b340: 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20 72 65  , free(), and re
b350: 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e  alloc() function
b360: 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
b370: 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  ard library..**.
b380: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
b390: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
b3a0: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
b3b0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b3c0: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
b3d0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
b3e0: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
b3f0: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
b400: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
b410: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
b420: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
b430: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
b440: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
b450: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
b460: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
b470: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
b480: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
b490: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
b4a0: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
b4b0: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
b4c0: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
b4d0: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
b4e0: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
b4f0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b500: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
b510: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
b520: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
b530: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
b540: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
b550: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
b560: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a   power of 2..**.
b570: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
b580: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
b590: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
b5a0: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
b5b0: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
b5c0: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
b5d0: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
b5e0: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
b5f0: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
b600: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
b610: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
b620: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
b630: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
b640: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b650: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
b660: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
b670: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
b680: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
b690: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
b6a0: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
b6b0: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
b6c0: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
b6d0: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79  xShutdown..*/.ty
b6e0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
b6f0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
b700: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
b710: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
b720: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
b730: 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
b740: 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
b750: 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
b760: 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
b770: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
b780: 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
b790: 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
b7a0: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
b7b0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
b7c0: 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
b7d0: 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
b7e0: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
b7f0: 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
b800: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
b810: 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
b820: 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
b830: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
b840: 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
b850: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
b860: 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
b870: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
b880: 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
b890: 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
b8a0: 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
b8b0: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
b8c0: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
b8d0: 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
b8e0: 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
b8f0: 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
b900: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
b910: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
b920: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
b930: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
b940: 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
b950: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
b960: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
b970: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
b980: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31  tion Options {H1
b990: 30 31 36 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  0160} <S20000>.*
b9a0: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
b9b0: 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
b9c0: 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
b9d0: 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
b9e0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
b9f0: 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
ba00: 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
ba10: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
ba20: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
ba30: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
ba40: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
ba50: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
ba60: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
ba70: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
ba80: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
ba90: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
baa0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
bab0: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
bac0: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
bad0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
bae0: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
baf0: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
bb00: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
bb10: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
bb20: 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
bb30: 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
bb40: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
bb50: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
bb60: 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
bb70: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
bb80: 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
bb90: 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
bba0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
bbb0: 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
bbc0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
bbd0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
bbe0: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
bbf0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
bc00: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
bc10: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
bc20: 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e  on.  This option
bc30: 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c   disables.** all
bc40: 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75   mutexing and pu
bc50: 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61  ts SQLite into a
bc60: 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63   mode where it c
bc70: 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a  an only be used.
bc80: 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ** by a single t
bc90: 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  hread.</dd>.**.*
bca0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
bcb0: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
bcc0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
bcd0: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
bce0: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
bcf0: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  n.  This option 
bd00: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
bd10: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
bd20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
bd30: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
bd40: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
bd50: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
bd60: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
bd70: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
bd80: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
bd90: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
bda0: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
bdb0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
bdc0: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
bdd0: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
bde0: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
bdf0: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
be00: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
be10: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
be20: 69 72 6f 6e 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a  ironment.</dd>.*
be30: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
be40: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
be50: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
be60: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
be70: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
be80: 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f  ion.  This optio
be90: 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
bea0: 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
beb0: 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
bec0: 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
bed0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
bee0: 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
bef0: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
bf00: 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
bf10: 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
bf20: 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
bf30: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
bf40: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
bf50: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
bf60: 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
bf70: 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
bf80: 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
bf90: 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
bfa0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
bfb0: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
bfc0: 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
bfd0: 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
bfe0: 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
bff0: 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
c000: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
c010: 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
c020: 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
c030: 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
c040: 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
c050: 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
c060: 2a 0a 2a 2a 20 3c 70 3e 54 68 69 73 20 63 6f 6e  *.** <p>This con
c070: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
c080: 6e 20 6d 65 72 65 6c 79 20 73 65 74 73 20 74 68  n merely sets th
c090: 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
c0a0: 0a 2a 2a 20 62 65 68 61 76 69 6f 72 20 74 6f 20  .** behavior to 
c0b0: 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
c0c0: 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f   to [database co
c0d0: 6e 6e 65 63 74 69 6f 6e 73 5d 2e 20 20 49 6e 64  nnections].  Ind
c0e0: 69 76 69 64 75 61 6c 0a 2a 2a 20 5b 64 61 74 61  ividual.** [data
c0f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
c100: 5d 20 63 61 6e 20 6f 76 65 72 72 69 64 65 20 74  ] can override t
c110: 68 69 73 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75  his setting.** u
c120: 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
c130: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
c140: 6c 61 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lag to [sqlite3_
c150: 6f 70 65 6e 5f 76 32 28 29 5d 2e 3c 2f 70 3e 3c  open_v2()].</p><
c160: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
c170: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
c180: 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
c190: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
c1a0: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
c1b0: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
c1c0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
c1d0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
c1e0: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
c1f0: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
c200: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
c210: 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
c220: 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
c230: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
c240: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
c250: 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
c260: 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
c270: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
c280: 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
c290: 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a   SQLite.</dd>.**
c2a0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
c2b0: 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c  ONFIG_GETMALLOC<
c2c0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
c2d0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
c2e0: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
c2f0: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
c300: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
c310: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
c320: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
c330: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
c340: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
c350: 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
c360: 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
c370: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
c380: 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
c390: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
c3a0: 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70  ines..** This op
c3b0: 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
c3c0: 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
c3d0: 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
c3e0: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
c3f0: 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
c400: 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c  apper that simul
c410: 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c  ations memory al
c420: 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
c430: 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65   or.** tracks me
c440: 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20  mory usage, for 
c450: 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a  example.</dd>.**
c460: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
c470: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
c480: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
c490: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
c4a0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
c4b0: 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
c4c0: 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
c4d0: 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
c4e0: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
c4f0: 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
c500: 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
c510: 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
c520: 73 74 69 63 73 2e 20 57 68 65 6e 20 64 69 73 61  stics. When disa
c530: 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77  bled, the follow
c540: 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
c550: 66 61 63 65 73 20 62 65 63 6f 6d 65 20 0a 2a 2a  faces become .**
c560: 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
c570: 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
c580: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
c590: 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
c5a0: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
c5b0: 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
c5c0: 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
c5d0: 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
c5e0: 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20  p_limit()].**   
c5f0: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
c600: 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  atus()].**   </u
c610: 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  l>.** </dd>.**.*
c620: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
c630: 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
c640: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
c650: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
c660: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
c670: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
c680: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
c690: 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
c6a0: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
c6b0: 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70   arguments:  A p
c6c0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
c6d0: 6d 6f 72 79 2c 20 74 68 65 0a 2a 2a 20 73 69 7a  mory, the.** siz
c6e0: 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63  e of each scratc
c6f0: 68 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61  h buffer (sz), a
c700: 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
c710: 20 62 75 66 66 65 72 73 20 28 4e 29 2e 20 20 54   buffers (N).  T
c720: 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e  he sz.** argumen
c730: 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74  t must be a mult
c740: 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68 65 20  iple of 16. The 
c750: 73 7a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f  sz parameter sho
c760: 75 6c 64 20 62 65 20 61 20 66 65 77 20 62 79 74  uld be a few byt
c770: 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74 68 61  es.** larger tha
c780: 6e 20 74 68 65 20 61 63 74 75 61 6c 20 73 63 72  n the actual scr
c790: 61 74 63 68 20 73 70 61 63 65 20 72 65 71 75 69  atch space requi
c7a0: 72 65 64 20 64 75 65 20 69 6e 74 65 72 6e 61 6c  red due internal
c7b0: 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68   overhead..** Th
c7c0: 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d  e first.** argum
c7d0: 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74  ent should point
c7e0: 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   to an allocatio
c7f0: 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  n of at least sz
c800: 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
c810: 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  ry..** SQLite wi
c820: 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74  ll use no more t
c830: 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20  han one scratch 
c840: 62 75 66 66 65 72 20 61 74 20 6f 6e 63 65 20 70  buffer at once p
c850: 65 72 20 74 68 72 65 61 64 2c 20 73 6f 0a 2a 2a  er thread, so.**
c860: 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74   N should be set
c870: 20 74 6f 20 74 68 65 20 65 78 70 65 63 74 65 64   to the expected
c880: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
c890: 6f 66 20 74 68 72 65 61 64 73 2e 20 20 54 68 65  of threads.  The
c8a0: 20 73 7a 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72   sz.** parameter
c8b0: 20 73 68 6f 75 6c 64 20 62 65 20 36 20 74 69 6d   should be 6 tim
c8c0: 65 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  es the size of t
c8d0: 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
c8e0: 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a  ase page size..*
c8f0: 2a 20 53 63 72 61 74 63 68 20 62 75 66 66 65 72  * Scratch buffer
c900: 73 20 61 72 65 20 75 73 65 64 20 61 73 20 70 61  s are used as pa
c910: 72 74 20 6f 66 20 74 68 65 20 62 74 72 65 65 20  rt of the btree 
c920: 62 61 6c 61 6e 63 65 20 6f 70 65 72 61 74 69 6f  balance operatio
c930: 6e 2e 20 20 49 66 0a 2a 2a 20 54 68 65 20 62 74  n.  If.** The bt
c940: 72 65 65 20 62 61 6c 61 6e 63 65 72 20 6e 65 65  ree balancer nee
c950: 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 20 6d 65  ds additional me
c960: 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74  mory beyond what
c970: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 0a   is provided by.
c980: 2a 2a 20 73 63 72 61 74 63 68 20 62 75 66 66 65  ** scratch buffe
c990: 72 73 20 6f 72 20 69 66 20 6e 6f 20 73 63 72 61  rs or if no scra
c9a0: 74 63 68 20 62 75 66 66 65 72 20 73 70 61 63 65  tch buffer space
c9b0: 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
c9c0: 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6f  hen SQLite.** go
c9d0: 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
c9e0: 61 6c 6c 6f 63 28 29 5d 20 74 6f 20 6f 62 74 61  alloc()] to obta
c9f0: 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 74  in the memory it
ca00: 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a   needs.</dd>.**.
ca10: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
ca20: 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
ca30: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
ca40: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
ca50: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
ca60: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
ca70: 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
ca80: 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
ca90: 70 61 67 65 20 63 61 63 68 65 2e 20 20 54 68 65  page cache.  The
caa0: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
cab0: 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65  uments: A pointe
cac0: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f  r to the.** memo
cad0: 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ry, the size of 
cae0: 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72  each page buffer
caf0: 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
cb00: 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28  umber of pages (
cb10: 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
cb20: 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
cb30: 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
cb40: 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
cb50: 37 36 38 2e 20 20 54 68 65 20 66 69 72 73 74 0a  768.  The first.
cb60: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
cb70: 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
cb80: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
cb90: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
cba0: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53   of memory..** S
cbb0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
cbc0: 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
cbd0: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
cbe0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69  argument to sati
cbf0: 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72  sfy its.** memor
cc00: 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20  y needs for the 
cc10: 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68  first N pages th
cc20: 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61  at it adds to ca
cc30: 63 68 65 2e 20 20 49 66 20 61 64 64 69 74 69 6f  che.  If additio
cc40: 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
cc50: 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
cc60: 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
cc70: 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
cc80: 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a  is option, then.
cc90: 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  ** SQLite goes t
cca0: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
ccb0: 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64  c()] for the add
ccc0: 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20  itional storage 
ccd0: 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6d  space..** The im
cce0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
ccf0: 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f  ht use one or mo
cd00: 72 65 20 6f 66 20 74 68 65 20 4e 20 62 75 66 66  re of the N buff
cd10: 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20  ers to hold .** 
cd20: 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e  memory accountin
cd30: 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 3c  g information. <
cd40: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
cd50: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
cd60: 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
cd70: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
cd80: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
cd90: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
cda0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
cdb0: 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ** for all of it
cdc0: 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
cdd0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
cde0: 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  s beyond those p
cdf0: 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62  rovided.** for b
ce00: 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
ce10: 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53  _SCRATCH] and [S
ce20: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
ce30: 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72  ECACHE]..** Ther
ce40: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
ce50: 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65 72  ments: A pointer
ce60: 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20   to the memory, 
ce70: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
ce80: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
ce90: 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
cea0: 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
ceb0: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 20 20 49  ocation size.  I
cec0: 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  f.** the first p
ced0: 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
cee0: 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
cef0: 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
cf00: 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
cf10: 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
cf20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
cf30: 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
cf40: 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
cf50: 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
cf60: 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
cf70: 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
cf80: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
cf90: 5d 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 6d 65  ].  If the.** me
cfa0: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
cfb0: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74  not NULL and eit
cfc0: 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  her [SQLITE_ENAB
cfd0: 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a  LE_MEMSYS3] or.*
cfe0: 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
cff0: 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65  _MEMSYS5] are de
d000: 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20  fined, then the 
d010: 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
d020: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20  ry.** allocator 
d030: 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61  is engaged to ha
d040: 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69  ndle all of SQLi
d050: 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tes memory alloc
d060: 61 74 69 6f 6e 20 6e 65 65 64 73 2e 3c 2f 64 64  ation needs.</dd
d070: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
d080: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
d090: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
d0a0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
d0b0: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
d0c0: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
d0d0: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
d0e0: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
d0f0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
d100: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
d110: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
d120: 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
d130: 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
d140: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
d150: 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
d160: 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20  ce.** the mutex 
d170: 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
d180: 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  nto SQLite.</dd>
d190: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
d1a0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
d1b0: 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  X</dt>.** <dd>Th
d1c0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
d1d0: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
d1e0: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
d1f0: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
d200: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
d210: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
d220: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
d230: 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
d240: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
d250: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
d260: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
d270: 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
d280: 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
d290: 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  s..** This optio
d2a0: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
d2b0: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
d2c0: 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
d2d0: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
d2e0: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
d2f0: 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
d300: 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
d310: 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
d320: 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
d330: 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
d340: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
d350: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
d360: 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
d370: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
d380: 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
d390: 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
d3a0: 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a  ine the default.
d3b0: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 63 61 74  ** memory allcat
d3c0: 69 6f 6e 20 6c 6f 6f 6b 61 73 69 64 65 20 6f 70  ion lookaside op
d3d0: 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 20 54 68 65  timization.  The
d3e0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
d3f0: 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
d400: 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
d410: 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
d420: 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
d430: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
d440: 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
d450: 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
d460: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 3c 2f 64 64   connection.</dd
d470: 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
d480: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d490: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
d4a0: 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
d4b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d4c0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
d4d0: 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
d4e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d4f0: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
d500: 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
d510: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d520: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
d530: 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
d540: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
d550: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
d560: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
d570: 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
d580: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
d590: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
d5a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
d5b0: 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
d5c0: 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
d5d0: 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
d5e0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d5f0: 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
d600: 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
d610: 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
d620: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
d630: 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
d640: 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
d650: 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
d660: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d670: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
d680: 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
d690: 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
d6a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
d6b0: 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
d6c0: 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
d6d0: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
d6e0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
d6f0: 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
d700: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
d710: 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
d720: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
d730: 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43  ONFIG_CHUNKALLOC
d740: 20 20 20 31 32 20 20 2f 2a 20 69 6e 74 20 74 68     12  /* int th
d750: 72 65 73 68 6f 6c 64 20 2a 2f 0a 23 64 65 66 69  reshold */.#defi
d760: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
d770: 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
d780: 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
d790: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d7a0: 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
d7b0: 70 74 69 6f 6e 73 20 7b 48 31 30 31 37 30 7d 20  ptions {H10170} 
d7c0: 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45  <S20000>.** EXPE
d7d0: 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
d7e0: 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
d7f0: 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
d800: 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
d810: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
d820: 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
d830: 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
d840: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
d850: 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
d860: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
d870: 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
d880: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
d890: 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
d8a0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
d8b0: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
d8c0: 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
d8d0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
d8e0: 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
d8f0: 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
d900: 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
d910: 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
d920: 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
d930: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
d940: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
d950: 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
d960: 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
d970: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
d980: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
d990: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
d9a0: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
d9b0: 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
d9c0: 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
d9d0: 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
d9e0: 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
d9f0: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
da00: 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
da10: 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
da20: 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
da30: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
da40: 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
da50: 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
da60: 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
da70: 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
da80: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
da90: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
daa0: 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
dab0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
dac0: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
dad0: 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
dae0: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
daf0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
db00: 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
db10: 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75  r to a memory bu
db20: 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
db30: 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
db40: 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  .  The first.** 
db50: 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20  argument may be 
db60: 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
db70: 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
db80: 6c 6c 6f 63 61 74 65 20 74 68 65 20 6c 6f 6f 6b  llocate the look
db90: 61 73 69 64 65 0a 2a 2a 20 62 75 66 66 65 72 20  aside.** buffer 
dba0: 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
dbb0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
dbc0: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67    The second arg
dbd0: 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
dbe0: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
dbf0: 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
dc00: 6f 74 20 61 6e 64 20 74 68 65 20 74 68 69 72 64  ot and the third
dc10: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
dc20: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
dc30: 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
dc40: 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
dc50: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
dc60: 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
dc70: 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
dc80: 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
dc90: 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
dca0: 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
dcb0: 65 6e 74 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ents.</dd>.**.**
dcc0: 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
dcd0: 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
dce0: 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
dcf0: 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e  001  /* void* in
dd00: 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a  t int */.../*.**
dd10: 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
dd20: 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
dd30: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
dd40: 65 73 20 7b 48 31 32 32 30 30 7d 20 3c 53 31 30  es {H12200} <S10
dd50: 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  700>.**.** The s
dd60: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
dd70: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
dd80: 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
dd90: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
dda0: 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
ddb0: 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
ddc0: 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 54 68 65  e of SQLite. The
ddd0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
dde0: 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
ddf0: 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
de00: 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
de10: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 63   compatibility c
de20: 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e 0a 2a  onsiderations..*
de30: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
de40: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 31 7d 20  .**.** {H12201} 
de50: 45 61 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61  Each new [databa
de60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
de70: 68 61 6c 6c 20 68 61 76 65 20 74 68 65 0a 2a 2a  hall have the.**
de80: 20 20 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e            [exten
de90: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
dea0: 5d 20 66 65 61 74 75 72 65 20 64 69 73 61 62 6c  ] feature disabl
deb0: 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
dec0: 2a 0a 2a 2a 20 7b 48 31 32 32 30 32 7d 20 54 68  *.** {H12202} Th
ded0: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  e [sqlite3_exten
dee0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
def0: 28 44 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 65  (D,F)] interface
df00: 20 73 68 61 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a   shall enable.**
df10: 20 20 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e            [exten
df20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
df30: 5d 20 66 6f 72 20 74 68 65 20 20 5b 64 61 74 61  ] for the  [data
df40: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
df50: 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69   D.**          i
df60: 66 20 74 68 65 20 46 20 70 61 72 61 6d 65 74 65  f the F paramete
df70: 72 20 69 73 20 74 72 75 65 2c 20 6f 72 20 64 69  r is true, or di
df80: 73 61 62 6c 65 20 74 68 65 6d 20 69 66 20 46 20  sable them if F 
df90: 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74  is false..*/.int
dfa0: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
dfb0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
dfc0: 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
dfd0: 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
dfe0: 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
dff0: 74 20 52 6f 77 69 64 20 7b 48 31 32 32 32 30 7d  t Rowid {H12220}
e000: 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10700>.**.** 
e010: 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e  Each entry in an
e020: 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61   SQLite table ha
e030: 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
e040: 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
e050: 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
e060: 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68 65 20  he "rowid". The 
e070: 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
e080: 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
e090: 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
e0a0: 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
e0b0: 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
e0c0: 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
e0d0: 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
e0e0: 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
e0f0: 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
e100: 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66  ared columns. If
e110: 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
e120: 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
e130: 70 65 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41  pe INTEGER PRIMA
e140: 52 59 20 4b 45 59 20 74 68 65 6e 20 74 68 61 74  RY KEY then that
e150: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
e160: 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
e170: 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
e180: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
e190: 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69 64 20  turns the rowid 
e1a0: 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  of the most rece
e1b0: 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  nt.** successful
e1c0: 20 49 4e 53 45 52 54 20 69 6e 74 6f 20 74 68 65   INSERT into the
e1d0: 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74   database from t
e1e0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
e1f0: 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74  nection].** in t
e200: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
e210: 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73  t.  If no succes
e220: 73 66 75 6c 20 49 4e 53 45 52 54 73 0a 2a 2a 20  sful INSERTs.** 
e230: 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
e240: 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62  ed on that datab
e250: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
e260: 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
e270: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e  ..**.** If an IN
e280: 53 45 52 54 20 6f 63 63 75 72 73 20 77 69 74 68  SERT occurs with
e290: 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68  in a trigger, th
e2a0: 65 6e 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  en the rowid of 
e2b0: 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20  the inserted.** 
e2c0: 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20  row is returned 
e2d0: 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
e2e0: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
e2f0: 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e  rigger is runnin
e300: 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
e310: 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69  he trigger termi
e320: 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65  nates, the value
e330: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
e340: 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76  s routine.** rev
e350: 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74  erts to the last
e360: 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20   value inserted 
e370: 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
e380: 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  er fired..**.** 
e390: 41 6e 20 49 4e 53 45 52 54 20 74 68 61 74 20 66  An INSERT that f
e3a0: 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
e3b0: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
e3c0: 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
e3d0: 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54  uccessful INSERT
e3e0: 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
e3f0: 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
e400: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
e410: 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75  ** routine.  Thu
e420: 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
e430: 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
e440: 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
e450: 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
e460: 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
e470: 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
e480: 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
e490: 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
e4a0: 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
e4b0: 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
e4c0: 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f  .  When INSERT O
e4d0: 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
e4e0: 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
e4f0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
e500: 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
e510: 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
e520: 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
e530: 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
e540: 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
e550: 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
e560: 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
e570: 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
e580: 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
e590: 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
e5a0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
e5b0: 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
e5c0: 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20  ..**.** For the 
e5d0: 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
e5e0: 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 49 4e 53   routine, an INS
e5f0: 45 52 54 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ERT is considere
e600: 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
e610: 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
e620: 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
e630: 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
e640: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
e650: 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32 31 7d 20 54  **.** {H12221} T
e660: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
e670: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
e680: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
e690: 73 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 20  s the rowid.**  
e6a0: 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6d          of the m
e6b0: 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65  ost recent succe
e6c0: 73 73 66 75 6c 20 49 4e 53 45 52 54 20 70 65 72  ssful INSERT per
e6d0: 66 6f 72 6d 65 64 20 6f 6e 20 74 68 65 20 73 61  formed on the sa
e6e0: 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  me.**          [
e6f0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
e700: 69 6f 6e 5d 20 61 6e 64 20 77 69 74 68 69 6e 20  ion] and within 
e710: 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68  the same or high
e720: 65 72 20 6c 65 76 65 6c 0a 2a 2a 20 20 20 20 20  er level.**     
e730: 20 20 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e       trigger con
e740: 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66  text, or zero if
e750: 20 74 68 65 72 65 20 68 61 76 65 20 62 65 65 6e   there have been
e760: 20 6e 6f 20 71 75 61 6c 69 66 79 69 6e 67 20 69   no qualifying i
e770: 6e 73 65 72 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nserts..**.** {H
e780: 31 32 32 32 33 7d 20 54 68 65 20 5b 73 71 6c 69  12223} The [sqli
e790: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
e7a0: 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f  rowid()] functio
e7b0: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  n returns the.**
e7c0: 20 20 20 20 20 20 20 20 20 20 73 61 6d 65 20 76            same v
e7d0: 61 6c 75 65 20 77 68 65 6e 20 63 61 6c 6c 65 64  alue when called
e7e0: 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
e7f0: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 0a 2a  rigger context.*
e800: 2a 20 20 20 20 20 20 20 20 20 20 69 6d 6d 65 64  *          immed
e810: 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 61 6e  iately before an
e820: 64 20 61 66 74 65 72 20 61 20 52 4f 4c 4c 42 41  d after a ROLLBA
e830: 43 4b 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50  CK..**.** ASSUMP
e840: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
e850: 32 32 33 32 7d 20 49 66 20 61 20 73 65 70 61 72  2232} If a separ
e860: 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
e870: 72 6d 73 20 61 20 6e 65 77 20 49 4e 53 45 52 54  rms a new INSERT
e880: 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
e890: 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73           databas
e8a0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
e8b0: 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
e8c0: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
e8d0: 64 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  d()].**         
e8e0: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
e8f0: 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
e900: 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
e910: 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a 2a 20  nsert rowid,.** 
e920: 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68           then th
e930: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
e940: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
e950: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
e960: 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] is.**         
e970: 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
e980: 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
e990: 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
e9a0: 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
e9b0: 20 20 20 20 20 20 20 20 20 6c 61 73 74 20 69 6e           last in
e9c0: 73 65 72 74 20 72 6f 77 69 64 2e 0a 2a 2f 0a 73  sert rowid..*/.s
e9d0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
e9e0: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
e9f0: 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
ea00: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
ea10: 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
ea20: 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
ea30: 66 69 65 64 20 7b 48 31 32 32 34 30 7d 20 3c 53  fied {H12240} <S
ea40: 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  10600>.**.** Thi
ea50: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
ea60: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
ea70: 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74   database rows t
ea80: 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64  hat were changed
ea90: 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20  .** or inserted 
eaa0: 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  or deleted by th
eab0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
eac0: 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74  completed SQL st
ead0: 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68  atement.** on th
eae0: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
eaf0: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
eb00: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70  d by the first p
eb10: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c  arameter..** Onl
eb20: 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61  y changes that a
eb30: 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63  re directly spec
eb40: 69 66 69 65 64 20 62 79 20 74 68 65 20 49 4e 53  ified by the INS
eb50: 45 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a 20  ERT, UPDATE,.** 
eb60: 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
eb70: 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ent are counted.
eb80: 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e    Auxiliary chan
eb90: 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a  ges caused by.**
eba0: 20 74 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f   triggers are no
ebb0: 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65 20 74  t counted. Use t
ebc0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
ebd0: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  l_changes()] fun
ebe0: 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64  ction.** to find
ebf0: 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
ec00: 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 63  r of changes inc
ec10: 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63  luding changes c
ec20: 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72  aused by trigger
ec30: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77 20  s..**.** A "row 
ec40: 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61  change" is a cha
ec50: 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20  nge to a single 
ec60: 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  row of a single 
ec70: 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20  table.** caused 
ec80: 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45  by an INSERT, DE
ec90: 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20  LETE, or UPDATE 
eca0: 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73  statement.  Rows
ecb0: 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61   that.** are cha
ecc0: 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66  nged as side eff
ecd0: 65 63 74 73 20 6f 66 20 52 45 50 4c 41 43 45 20  ects of REPLACE 
ece0: 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
ecf0: 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61  ution,.** rollba
ed00: 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73  ck, ABORT proces
ed10: 73 69 6e 67 2c 20 44 52 4f 50 20 54 41 42 4c 45  sing, DROP TABLE
ed20: 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65  , or by any othe
ed30: 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20  r.** mechanisms 
ed40: 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20  do not count as 
ed50: 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67  direct row chang
ed60: 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69  es..**.** A "tri
ed70: 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73  gger context" is
ed80: 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63   a scope of exec
ed90: 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e  ution that begin
eda0: 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69  s and.** ends wi
edb0: 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66  th the script of
edc0: 20 61 20 74 72 69 67 67 65 72 2e 20 20 4d 6f 73   a trigger.  Mos
edd0: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
ede0: 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65   are.** evaluate
edf0: 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79  d outside of any
ee00: 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 20   trigger.  This 
ee10: 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65  is the "top leve
ee20: 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  l".** trigger co
ee30: 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 69  ntext.  If a tri
ee40: 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20  gger fires from 
ee50: 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61  the top level, a
ee60: 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20  .** new trigger 
ee70: 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72  context is enter
ee80: 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74  ed for the durat
ee90: 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a  ion of that one.
eea0: 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 62  ** trigger.  Sub
eeb0: 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65 20  triggers create 
eec0: 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20  subcontexts for 
eed0: 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a  their duration..
eee0: 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b 73  **.** Calling [s
eef0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f  qlite3_exec()] o
ef00: 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
ef10: 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64  )] recursively d
ef20: 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74  oes.** not creat
ef30: 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20  e a new trigger 
ef40: 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54  context..**.** T
ef50: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
ef60: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
ef70: 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  of direct row ch
ef80: 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20  anges in the.** 
ef90: 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
efa0: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
efb0: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
efc0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a  within the same.
efd0: 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
efe0: 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73 2c 20  xt..**.** Thus, 
eff0: 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d  when called from
f000: 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
f010: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
f020: 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  turns the.** num
f030: 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69  ber of changes i
f040: 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
f050: 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
f060: 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
f070: 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65  hat also occurre
f080: 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76  d at the top lev
f090: 65 6c 2e 20 20 57 69 74 68 69 6e 20 74 68 65 20  el.  Within the 
f0a0: 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65  body of a trigge
f0b0: 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  r,.** the sqlite
f0c0: 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65  3_changes() inte
f0d0: 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c  rface can be cal
f0e0: 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  led to find the 
f0f0: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
f100: 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
f110: 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
f120: 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
f130: 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
f140: 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
f150: 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68  n the body of th
f160: 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
f170: 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
f180: 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20  number returned 
f190: 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
f1a0: 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73   changes.** caus
f1b0: 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72  ed by subtrigger
f1c0: 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61  s since those ha
f1d0: 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e  ve their own con
f1e0: 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  text..**.** SQLi
f1f0: 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
f200: 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54  e command "DELET
f210: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69  E FROM table" wi
f220: 74 68 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c  thout a WHERE cl
f230: 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70  ause.** by dropp
f240: 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74 69  ing and recreati
f250: 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28  ng the table.  (
f260: 54 68 69 73 20 69 73 20 6d 75 63 68 20 66 61 73  This is much fas
f270: 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a  ter than going.*
f280: 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65  * through and de
f290: 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61  leting individua
f2a0: 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20  l elements from 
f2b0: 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63  the table.)  Bec
f2c0: 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  ause of this.** 
f2d0: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68  optimization, th
f2e0: 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22  e deletions in "
f2f0: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
f300: 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63  e" are not row c
f310: 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69  hanges and.** wi
f320: 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65  ll not be counte
f330: 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
f340: 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73  _changes() or [s
f350: 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
f360: 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  nges()].** funct
f370: 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 73  ions, regardless
f380: 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
f390: 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20  f elements that 
f3a0: 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  were originally.
f3b0: 2a 2a 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e  ** in the table.
f3c0: 20 20 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75    To get an accu
f3d0: 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68  rate count of th
f3e0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
f3f0: 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a   deleted, use.**
f400: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
f410: 62 6c 65 20 57 48 45 52 45 20 31 22 20 69 6e 73  ble WHERE 1" ins
f420: 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  tead..**.** INVA
f430: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
f440: 31 32 32 34 31 7d 20 54 68 65 20 5b 73 71 6c 69  12241} The [sqli
f450: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  te3_changes()] f
f460: 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65  unction shall re
f470: 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
f480: 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  of.**          r
f490: 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ow changes cause
f4a0: 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
f4b0: 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
f4c0: 41 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ATE,.**         
f4d0: 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
f4e0: 6d 65 6e 74 20 6f 6e 20 74 68 65 20 73 61 6d 65  ment on the same
f4f0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
f500: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20  tion and.**     
f510: 20 20 20 20 20 77 69 74 68 69 6e 20 74 68 65 20       within the 
f520: 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72 20 74  same or higher t
f530: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20  rigger context, 
f540: 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65  or zero if there
f550: 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20   have.**        
f560: 20 20 6e 6f 74 20 62 65 65 6e 20 61 6e 79 20 71    not been any q
f570: 75 61 6c 69 66 79 69 6e 67 20 72 6f 77 20 63 68  ualifying row ch
f580: 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  anges..**.** {H1
f590: 32 32 34 33 7d 20 53 74 61 74 65 6d 65 6e 74 73  2243} Statements
f5a0: 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45   of the form "DE
f5b0: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e  LETE FROM tablen
f5c0: 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20  ame" with no.** 
f5d0: 20 20 20 20 20 20 20 20 20 57 48 45 52 45 20 63           WHERE c
f5e0: 6c 61 75 73 65 20 73 68 61 6c 6c 20 63 61 75 73  lause shall caus
f5f0: 65 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  e subsequent cal
f600: 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ls to.**        
f610: 20 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67    [sqlite3_chang
f620: 65 73 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20  es()] to return 
f630: 7a 65 72 6f 2c 20 72 65 67 61 72 64 6c 65 73 73  zero, regardless
f640: 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
f650: 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f      number of ro
f660: 77 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e  ws originally in
f670: 20 74 68 65 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a   the table..**.*
f680: 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a  * ASSUMPTIONS:.*
f690: 2a 0a 2a 2a 20 7b 41 31 32 32 35 32 7d 20 49 66  *.** {A12252} If
f6a0: 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
f6b0: 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
f6c0: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
f6d0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f6e0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69  .**          whi
f6f0: 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
f700: 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
f710: 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
f720: 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20   returned.**    
f730: 20 20 20 20 20 20 69 73 20 75 6e 70 72 65 64 69        is unpredi
f740: 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
f750: 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
f760: 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
f770: 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
f780: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
f790: 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
f7a0: 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32  ws Modified {H12
f7b0: 32 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a  260} <S10600>.**
f7c0: 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
f7d0: 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
f7e0: 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
f7f0: 67 65 73 20 63 61 75 73 65 64 20 62 79 20 49 4e  ges caused by IN
f800: 53 45 52 54 2c 0a 2a 2a 20 55 50 44 41 54 45 20  SERT,.** UPDATE 
f810: 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
f820: 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b  ents since the [
f830: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f840: 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e  ion] was opened.
f850: 0a 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20 69 6e  .** The count in
f860: 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67  cludes all chang
f870: 65 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72 69 67  es from all trig
f880: 67 65 72 20 63 6f 6e 74 65 78 74 73 2e 20 20 48  ger contexts.  H
f890: 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63  owever,.** the c
f8a0: 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
f8b0: 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73  clude changes us
f8c0: 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
f8d0: 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69  REPLACE constrai
f8e0: 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62  nts,.** do rollb
f8f0: 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72  acks or ABORT pr
f900: 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 44 52 4f  ocessing, or DRO
f910: 50 20 74 61 62 6c 65 20 70 72 6f 63 65 73 73 69  P table processi
f920: 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67  ng..** The chang
f930: 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61  es are counted a
f940: 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74  s soon as the st
f950: 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b  atement that mak
f960: 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f  es them is.** co
f970: 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
f980: 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
f990: 6c 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 20  le is passed to 
f9a0: 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
f9b0: 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
f9c0: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
f9d0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c  *.** SQLite impl
f9e0: 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61  ements the comma
f9f0: 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  nd "DELETE FROM 
fa00: 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61  table" without a
fa10: 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a   WHERE clause.**
fa20: 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64   by dropping and
fa30: 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20   recreating the 
fa40: 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73  table.  (This is
fa50: 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61   much faster tha
fa60: 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75  n going.** throu
fa70: 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20  gh and deleting 
fa80: 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65  individual eleme
fa90: 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62  nts from the tab
faa0: 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66  le.)  Because of
fab0: 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a   this.** optimiz
fac0: 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74  ation, the delet
fad0: 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20  ions in "DELETE 
fae0: 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20  FROM table" are 
faf0: 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  not row changes 
fb00: 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  and.** will not 
fb10: 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68  be counted by th
fb20: 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
fb30: 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  s() or [sqlite3_
fb40: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
fb50: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72  .** functions, r
fb60: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
fb70: 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65   number of eleme
fb80: 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72  nts that were or
fb90: 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74  iginally.** in t
fba0: 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65  he table.  To ge
fbb0: 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f  t an accurate co
fbc0: 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  unt of the numbe
fbd0: 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65  r of rows delete
fbe0: 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54  d, use.** "DELET
fbf0: 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45  E FROM table WHE
fc00: 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a  RE 1" instead..*
fc10: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
fc20: 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
fc30: 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  es()] interface.
fc40: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
fc50: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 31  S:.**.** {H12261
fc60: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  } The [sqlite3_t
fc70: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
fc80: 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61  returns the tota
fc90: 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20  l number.**     
fca0: 20 20 20 20 20 6f 66 20 72 6f 77 20 63 68 61 6e       of row chan
fcb0: 67 65 73 20 63 61 75 73 65 64 20 62 79 20 49 4e  ges caused by IN
fcc0: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 61 6e  SERT, UPDATE, an
fcd0: 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 20  d/or DELETE.**  
fce0: 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e          statemen
fcf0: 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ts on the same [
fd00: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
fd10: 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20  ion], in any.** 
fd20: 20 20 20 20 20 20 20 20 20 74 72 69 67 67 65 72           trigger
fd30: 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63 65 20   context, since 
fd40: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
fd50: 6e 65 63 74 69 6f 6e 20 77 61 73 20 63 72 65 61  nection was crea
fd60: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  ted..**.** {H122
fd70: 36 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f  63} Statements o
fd80: 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45  f the form "DELE
fd90: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d  TE FROM tablenam
fda0: 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20  e" with no.**   
fdb0: 20 20 20 20 20 20 20 57 48 45 52 45 20 63 6c 61         WHERE cla
fdc0: 75 73 65 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68  use shall not ch
fdd0: 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
fde0: 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20  eturned.**      
fdf0: 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f      by [sqlite3_
fe00: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
fe10: 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49  ..**.** ASSUMPTI
fe20: 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32  ONS:.**.** {A122
fe30: 36 34 7d 20 49 66 20 61 20 73 65 70 61 72 61 74  64} If a separat
fe40: 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
fe50: 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
fe60: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
fe70: 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
fe80: 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65     while [sqlite
fe90: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
fea0: 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
feb0: 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
fec0: 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 65           returne
fed0: 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
fee0: 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
fef0: 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
ff00: 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
ff10: 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
ff20: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ff30: 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
ff40: 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b  -Running Query {
ff50: 48 31 32 32 37 30 7d 20 3c 53 33 30 35 30 30 3e  H12270} <S30500>
ff60: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
ff70: 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
ff80: 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
ff90: 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
ffa0: 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
ffb0: 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
ffc0: 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
ffd0: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
ffe0: 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
fff0: 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
10000 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
10010 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
10020 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
10030 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
10040 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
10050 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
10060 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
10070 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
10080 20 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63   It is safe to c
10090 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
100a0 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
100b0 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
100c0 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
100d0 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
100e0 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
100f0 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
10100 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
10110 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
10120 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
10130 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10140 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
10150 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
10160 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
10170 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
10180 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
10190 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72  * If an SQL oper
101a0 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
101b0 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
101c0 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
101d0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
101e0 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
101f0 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
10200 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
10210 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
10220 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
10230 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
10240 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
10250 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61  .** An SQL opera
10260 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
10270 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
10280 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
10290 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74  ERRUPT]..** If t
102a0 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
102b0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
102c0 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
102d0 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
102e0 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
102f0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
10300 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
10310 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
10320 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
10330 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
10340 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
10350 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
10360 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 68 61  3_interrupt() ha
10370 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
10380 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
10390 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
103a0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
103b0 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
103c0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  rns..**.** INVAR
103d0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
103e0 32 32 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2271} The [sqlit
103f0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20  e3_interrupt()] 
10400 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 66  interface will f
10410 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e 69 6e 67  orce all running
10420 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c  .**          SQL
10430 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
10440 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
10450 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
10460 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
10470 20 20 20 20 20 74 6f 20 68 61 6c 74 20 61 66 74       to halt aft
10480 65 72 20 70 72 6f 63 65 73 73 69 6e 67 20 61 74  er processing at
10490 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64 69 74 69   most one additi
104a0 6f 6e 61 6c 20 72 6f 77 20 6f 66 20 64 61 74 61  onal row of data
104b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 32 7d  ..**.** {H12272}
104c0 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65   Any SQL stateme
104d0 6e 74 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  nt that is inter
104e0 72 75 70 74 65 64 20 62 79 20 5b 73 71 6c 69 74  rupted by [sqlit
104f0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
10500 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c  **          will
10510 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
10520 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a  INTERRUPT]..**.*
10530 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a  * ASSUMPTIONS:.*
10540 2a 0a 2a 2a 20 7b 41 31 32 32 37 39 7d 20 49 66  *.** {A12279} If
10550 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
10560 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
10570 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
10580 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20  nterrupt()].**  
10590 20 20 20 20 20 20 20 20 69 73 20 72 75 6e 6e 69          is runni
105a0 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
105b0 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
105c0 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73  appen..*/.void s
105d0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
105e0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
105f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
10600 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
10610 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
10620 6d 70 6c 65 74 65 20 7b 48 31 30 35 31 30 7d 20  mplete {H10510} 
10630 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S70200>.**.** T
10640 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
10650 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d  e useful for com
10660 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
10670 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
10680 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
10690 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
106a0 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d 70  ems to form comp
106b0 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61 74 65  lete a SQL state
106c0 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
106d0 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
106e0 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
106f0 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
10700 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
10710 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 54 68  for parsing.  Th
10720 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
10730 75 72 6e 20 74 72 75 65 20 69 66 20 74 68 65 20  urn true if the 
10740 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
10750 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
10760 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
10770 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 65  tement.  A state
10780 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
10790 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
107a0 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
107b0 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
107c0 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
107d0 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a  fragment of a.**
107e0 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
107f0 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d 69  statement.  Semi
10800 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
10810 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
10820 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
10830 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
10840 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
10850 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
10860 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
10870 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
10880 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
10890 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
108a0 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
108b0 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
108c0 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
108d0 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
108e0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  or..**.** These 
108f0 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
10900 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
10910 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
10920 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
10930 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
10940 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
10950 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
10960 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 31 7d 20 41  **.** {H10511} A
10970 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 61 6c   successful eval
10980 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  uation of [sqlit
10990 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f  e3_complete()] o
109a0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
109b0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
109c0 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73 20 73  6()] functions s
109d0 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  hall.**         
109e0 20 72 65 74 75 72 6e 20 61 20 6e 75 6d 65 72 69   return a numeri
109f0 63 20 31 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  c 1 if and only 
10a00 69 66 20 74 68 65 20 6c 61 73 74 20 6e 6f 6e 2d  if the last non-
10a10 77 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 20 20  whitespace.**   
10a20 20 20 20 20 20 20 20 74 6f 6b 65 6e 20 69 6e 20         token in 
10a30 74 68 65 69 72 20 69 6e 70 75 74 20 69 73 20 61  their input is a
10a40 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 74 20   semicolon that 
10a50 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77 65 65  is not in betwee
10a60 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
10a70 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e 44 20  e BEGIN and END 
10a80 6f 66 20 61 20 43 52 45 41 54 45 20 54 52 49 47  of a CREATE TRIG
10a90 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  GER statement..*
10aa0 2a 0a 2a 2a 20 7b 48 31 30 35 31 32 7d 20 49 66  *.** {H10512} If
10ab0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
10ac0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
10ad0 73 20 64 75 72 69 6e 67 20 61 6e 20 69 6e 76 6f  s during an invo
10ae0 63 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  cation.**       
10af0 20 20 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63     of [sqlite3_c
10b00 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 20 5b 73  omplete()] or [s
10b10 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
10b20 36 28 29 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  6()] then the.**
10b30 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e            routin
10b40 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b  e shall return [
10b50 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
10b60 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
10b70 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 32 7d  :.**.** {A10512}
10b80 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
10b90 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
10ba0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
10bb0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
10bc0 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73           UTF-8 s
10bd0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31  tring..**.** {A1
10be0 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75 74 20  0513} The input 
10bf0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
10c00 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
10c10 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
10c20 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
10c30 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
10c40 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
10c50 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
10c60 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
10c70 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
10c80 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
10c90 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
10ca0 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
10cb0 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
10cc0 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
10cd0 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
10ce0 59 20 45 72 72 6f 72 73 20 7b 48 31 32 33 31 30  Y Errors {H12310
10cf0 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <S40400>.**.**
10d00 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65   This routine se
10d10 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
10d20 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68  nction that migh
10d30 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  t be invoked whe
10d40 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65  never.** an atte
10d50 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  mpt is made to o
10d60 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74  pen a database t
10d70 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65  able that anothe
10d80 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
10d90 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65  rocess has locke
10da0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
10db0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  busy callback is
10dc0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c   NULL, then [SQL
10dd0 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
10de0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
10df0 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ED].** is return
10e00 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75  ed immediately u
10e10 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67  pon encountering
10e20 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20 74 68   the lock. If th
10e30 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
10e40 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
10e50 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
10e60 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  k will be invoke
10e70 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
10e80 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
10e90 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
10ea0 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73  o the handler is
10eb0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
10ec0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
10ed0 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
10ee0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
10ef0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
10f00 6c 65 72 28 29 2e 20 20 54 68 65 20 73 65 63 6f  ler().  The seco
10f10 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
10f20 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 63 61  * the handler ca
10f30 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
10f40 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
10f50 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
10f60 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
10f70 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73  invoked for this
10f80 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
10f90 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20   If the.** busy 
10fa0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
10fb0 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
10fc0 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
10fd0 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
10fe0 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
10ff0 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
11000 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
11010 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
11020 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49  s returned..** I
11030 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
11040 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
11050 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
11060 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
11070 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
11080 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e  abase for readin
11090 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  g and the cycle 
110a0 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
110b0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
110c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
110d0 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
110e0 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
110f0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
11100 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
11110 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20 53 51  ontention. If SQ
11120 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
11130 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
11140 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
11150 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
11160 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
11170 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
11180 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
11190 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53  E_BUSY].** or [S
111a0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
111b0 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20  KED] instead of 
111c0 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
111d0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
111e0 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
111f0 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
11200 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
11210 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
11220 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
11230 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
11240 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
11250 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
11260 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
11270 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
11280 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
11290 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
112a0 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
112b0 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
112c0 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
112d0 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
112e0 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
112f0 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
11300 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
11310 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
11320 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
11330 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
11340 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
11350 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
11360 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
11370 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
11380 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
11390 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
113a0 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
113b0 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
113c0 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
113d0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
113e0 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
113f0 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
11400 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
11410 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
11420 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
11430 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
11440 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
11450 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  oceed..**.** The
11460 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
11470 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
11480 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
11490 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73  E_BUSY] error is
114a0 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53   converted to [S
114b0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
114c0 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  KED].** when SQL
114d0 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69  ite is in the mi
114e0 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20  ddle of a large 
114f0 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72  transaction wher
11500 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61  e all the.** cha
11510 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69  nges will not fi
11520 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65  t into the in-me
11530 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c  mory cache.  SQL
11540 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65  ite will.** alre
11550 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52  ady hold a RESER
11560 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  VED lock on the 
11570 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62  database file, b
11580 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74  ut it needs.** t
11590 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c  o promote this l
115a0 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45  ock to EXCLUSIVE
115b0 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20   so that it can 
115c0 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70  spill cache.** p
115d0 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61  ages into the da
115e0 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68  tabase file with
115f0 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63  out harm to conc
11600 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72  urrent.** reader
11610 73 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e 61  s.  If it is una
11620 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ble to promote t
11630 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68  he lock, then th
11640 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63  e in-memory.** c
11650 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66  ache will be lef
11660 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73  t in an inconsis
11670 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73  tent state and s
11680 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63  o the error.** c
11690 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20  ode is promoted 
116a0 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76  from the relativ
116b0 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49  ely benign [SQLI
116c0 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74  TE_BUSY] to.** t
116d0 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b  he more severe [
116e0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
116f0 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72  CKED].  This err
11700 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f  or code promotio
11710 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61  n.** forces an a
11720 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63  utomatic rollbac
11730 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73  k of the changes
11740 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61  .  See the.** <a
11750 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f   href="/cvstrac/
11760 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f  wiki?p=Corruptio
11770 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
11780 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74  ror">.** Corrupt
11790 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
117a0 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70  Error</a> wiki p
117b0 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73  age for a discus
117c0 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74  sion of why.** t
117d0 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74  his is important
117e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61  ..**.** There ca
117f0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
11800 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
11810 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
11820 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
11830 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
11840 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
11850 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
11860 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
11870 73 65 74 20 68 61 6e 64 6c 65 72 2e 20 20 4e 6f  set handler.  No
11880 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
11890 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
118a0 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c  meout()].** will
118b0 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65   also set or cle
118c0 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ar the busy hand
118d0 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ler..**.** INVAR
118e0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
118f0 32 33 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2311} The [sqlit
11900 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
11910 44 2c 43 2c 41 29 5d 20 66 75 6e 63 74 69 6f 6e  D,C,A)] function
11920 20 73 68 61 6c 6c 20 72 65 70 6c 61 63 65 0a 2a   shall replace.*
11930 2a 20 20 20 20 20 20 20 20 20 20 62 75 73 79 20  *          busy 
11940 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65 20  callback in the 
11950 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11960 74 69 6f 6e 5d 20 44 20 77 69 74 68 20 61 20 6e  tion] D with a n
11970 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ew.**          a
11980 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
11990 72 20 43 20 61 6e 64 20 61 70 70 6c 69 63 61 74  r C and applicat
119a0 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
119b0 20 41 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31   A..**.** {H1231
119c0 32 7d 20 4e 65 77 6c 79 20 63 72 65 61 74 65 64  2} Newly created
119d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
119e0 63 74 69 6f 6e 73 5d 20 73 68 61 6c 6c 20 68 61  ctions] shall ha
119f0 76 65 20 61 20 62 75 73 79 0a 2a 2a 20 20 20 20  ve a busy.**    
11a00 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20 6f 66        handler of
11a10 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   NULL..**.** {H1
11a20 32 33 31 34 7d 20 57 68 65 6e 20 74 77 6f 20 6f  2314} When two o
11a30 72 20 6d 6f 72 65 20 5b 64 61 74 61 62 61 73 65  r more [database
11a40 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 73 68   connections] sh
11a50 61 72 65 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  are a.**        
11a60 20 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c    [sqlite3_enabl
11a70 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 20 7c  e_shared_cache |
11a80 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d 2c 0a   common cache],.
11a90 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
11aa0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
11ab0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
11ac0 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 65 6e 74  nnection current
11ad0 6c 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ly using.**     
11ae0 20 20 20 20 20 74 68 65 20 63 61 63 68 65 20 73       the cache s
11af0 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20  hall be invoked 
11b00 77 68 65 6e 20 74 68 65 20 63 61 63 68 65 20 65  when the cache e
11b10 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f 63 6b  ncounters a lock
11b20 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 36 7d  ..**.** {H12316}
11b30 20 49 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   If a busy handl
11b40 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
11b50 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74  rns zero, then t
11b60 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  he SQLite interf
11b70 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ace.**          
11b80 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68  that provoked th
11b90 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 20  e locking event 
11ba0 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51  shall return [SQ
11bb0 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
11bc0 2a 20 7b 48 31 32 33 31 38 7d 20 53 51 4c 69 74  * {H12318} SQLit
11bd0 65 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 73 20  e shall invokes 
11be0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
11bf0 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
11c00 6e 74 73 20 77 68 69 63 68 0a 2a 2a 20 20 20 20  nts which.**    
11c10 20 20 20 20 20 20 61 72 65 20 61 20 63 6f 70 79        are a copy
11c20 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65 72 20   of the pointer 
11c30 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20  supplied by the 
11c40 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
11c50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
11c60 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
11c70 65 72 28 29 5d 20 61 6e 64 20 61 20 63 6f 75 6e  er()] and a coun
11c80 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  t of the number 
11c90 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20  of prior.**     
11ca0 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 73       invocations
11cb0 20 6f 66 20 74 68 65 20 62 75 73 79 20 68 61 6e   of the busy han
11cc0 64 6c 65 72 20 66 6f 72 20 74 68 65 20 73 61 6d  dler for the sam
11cd0 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  e locking event.
11ce0 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f  .**.** ASSUMPTIO
11cf0 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 33 31  NS:.**.** {A1231
11d00 39 7d 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  9} A busy handle
11d10 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
11d20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
11d30 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
11d40 20 20 20 20 20 6f 72 20 5b 70 72 65 70 61 72 65       or [prepare
11d50 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
11d60 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
11d70 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
11d80 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
11d90 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
11da0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
11db0 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
11dc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
11dd0 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
11de0 20 7b 48 31 32 33 34 30 7d 20 3c 53 34 30 34 31   {H12340} <S4041
11df0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
11e00 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
11e10 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
11e20 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
11e30 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
11e40 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
11e50 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
11e60 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
11e70 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61   locked.  The ha
11e80 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
11e90 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
11ea0 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
11eb0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
11ec0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
11ed0 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
11ee0 74 65 64 2e 20 7b 48 31 32 33 34 33 7d 20 41 66  ted. {H12343} Af
11ef0 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ter "ms" millise
11f00 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
11f10 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  g,.** the handle
11f20 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
11f30 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  h causes [sqlite
11f40 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
11f50 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  urn.** [SQLITE_B
11f60 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
11f70 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a  IOERR_BLOCKED]..
11f80 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68  **.** Calling th
11f90 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
11fa0 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73  an argument less
11fb0 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
11fc0 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20  o zero.** turns 
11fd0 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e  off all busy han
11fe0 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dlers..**.** The
11ff0 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
12000 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
12010 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
12020 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
12030 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
12040 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  ny any given mom
12050 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
12060 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
12070 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
12080 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
12090 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
120a0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
120b0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
120c0 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
120d0 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
120e0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  red..**.** INVAR
120f0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
12100 32 33 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2341} The [sqlit
12110 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
12120 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c  )] function shal
12130 6c 20 6f 76 65 72 72 69 64 65 20 61 6e 79 20 70  l override any p
12140 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rior.**         
12150 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
12160 69 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73 71  imeout()] or [sq
12170 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
12180 65 72 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a 2a  er()] setting.**
12190 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65            on the
121a0 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
121b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  connection]..**.
121c0 2a 2a 20 7b 48 31 32 33 34 33 7d 20 49 66 20 74  ** {H12343} If t
121d0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
121e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73   to [sqlite3_bus
121f0 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20  y_timeout()] is 
12200 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20  less than.**    
12210 20 20 20 20 20 20 6f 72 20 65 71 75 61 6c 20 74        or equal t
12220 6f 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  o zero, then the
12230 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68   busy handler sh
12240 61 6c 6c 20 62 65 20 63 6c 65 61 72 65 64 20 73  all be cleared s
12250 6f 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20  o that.**       
12260 20 20 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e     all subsequen
12270 74 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 73  t locking events
12280 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74   immediately ret
12290 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
122a0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 34  ]..**.** {H12344
122b0 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70 61 72  } If the 2nd par
122c0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
122d0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
122e0 29 5d 20 69 73 20 61 20 70 6f 73 69 74 69 76 65  )] is a positive
122f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
12300 62 65 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 75  ber N, then a bu
12310 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c  sy handler shall
12320 20 62 65 20 73 65 74 20 74 68 61 74 20 72 65 70   be set that rep
12330 65 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a  eatedly calls.**
12340 20 20 20 20 20 20 20 20 20 20 74 68 65 20 78 53            the xS
12350 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 69 6e  leep() method in
12360 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
12370 73 20 7c 20 56 46 53 20 69 6e 74 65 72 66 61 63  s | VFS interfac
12380 65 5d 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20  e] until.**     
12390 20 20 20 20 20 65 69 74 68 65 72 20 74 68 65 20       either the 
123a0 6c 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72 20 75  lock clears or u
123b0 6e 74 69 6c 20 74 68 65 20 63 75 6d 75 6c 61 74  ntil the cumulat
123c0 69 76 65 20 73 6c 65 65 70 20 74 69 6d 65 0a 2a  ive sleep time.*
123d0 2a 20 20 20 20 20 20 20 20 20 20 72 65 70 6f 72  *          repor
123e0 74 65 64 20 62 61 63 6b 20 62 79 20 78 53 6c 65  ted back by xSle
123f0 65 70 28 29 20 65 78 63 65 65 64 73 20 4e 20 6d  ep() exceeds N m
12400 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a  illiseconds..*/.
12410 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
12420 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
12430 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
12440 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
12450 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
12460 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
12470 65 72 69 65 73 20 7b 48 31 32 33 37 30 7d 20 3c  eries {H12370} <
12480 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 65  S10000>.**.** De
12490 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
124a0 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
124b0 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
124c0 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
124d0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
124e0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
124f0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
12500 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
12510 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
12520 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
12530 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
12540 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
12550 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
12560 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
12570 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
12580 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
12590 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
125a0 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
125b0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
125c0 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
125d0 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
125e0 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
125f0 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
12600 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
12610 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
12620 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
12630 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
12640 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
12650 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
12660 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
12670 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
12680 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
12690 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
126a0 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
126b0 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
126c0 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
126d0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
126e0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
126f0 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
12700 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
12710 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
12720 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
12730 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
12740 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
12750 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
12760 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
12770 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
12780 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
12790 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
127a0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
127b0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
127c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
127d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
127e0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
127f0 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
12800 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
12810 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
12820 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
12830 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
12840 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
12850 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
12860 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
12870 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
12880 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
12890 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
128a0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
128b0 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  able()]..**.** A
128c0 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
128d0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
128e0 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
128f0 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
12900 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
12910 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
12920 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
12930 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
12940 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
12950 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
12960 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
12970 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
12980 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
12990 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
129a0 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
129b0 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
129c0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
129d0 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
129e0 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
129f0 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
12a00 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
12a10 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
12a20 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
12a30 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
12a40 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
12a50 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
12a60 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
12a70 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
12a80 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
12a90 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
12aa0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
12ab0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
12ac0 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
12ad0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
12ae0 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
12af0 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
12b00 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
12b10 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
12b20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
12b30 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
12b40 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
12b50 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
12b60 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
12b70 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
12b80 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
12b90 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
12ba0 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
12bb0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
12bc0 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
12bd0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
12be0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
12bf0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
12c00 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
12c10 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
12c20 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
12c30 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
12c40 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
12c50 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
12c60 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
12c70 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  s 2nd parameter.
12c80 20 20 49 74 20 72 65 74 75 72 6e 73 20 61 20 72    It returns a r
12c90 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
12ca0 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
12cb0 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
12cc0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
12cd0 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e  After the callin
12ce0 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66  g function has f
12cf0 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
12d00 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f  e result, it sho
12d10 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68 65 20  uld.** pass the 
12d20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72  pointer to the r
12d30 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73  esult table to s
12d40 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
12d50 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  e() in order to.
12d60 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  ** release the m
12d70 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d  emory that was m
12d80 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73  alloced.  Becaus
12d90 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65  e of the way the
12da0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
12db0 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77  loc()] happens w
12dc0 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65  ithin sqlite3_ge
12dd0 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63  t_table(), the c
12de0 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  alling.** functi
12df0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20  on must not try 
12e00 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  to call [sqlite3
12e10 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c  _free()] directl
12e20 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c  y.  Only.** [sql
12e30 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
12e40 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65  )] is able to re
12e50 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
12e60 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61   properly and sa
12e70 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fely..**.** The 
12e80 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
12e90 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
12ea0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20   implemented as 
12eb0 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  a wrapper around
12ec0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
12ed0 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74  c()].  The sqlit
12ee0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72  e3_get_table() r
12ef0 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20  outine does not 
12f00 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  have access.** t
12f10 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64  o any internal d
12f20 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f  ata structures o
12f30 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73  f SQLite.  It us
12f40 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c  es only the publ
12f50 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ic.** interface 
12f60 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41  defined here.  A
12f70 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c  s a consequence,
12f80 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
12f90 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61  ur in the.** wra
12fa0 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69  pper layer outsi
12fb0 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e  de of the intern
12fc0 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  al [sqlite3_exec
12fd0 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74  ()] call are not
12fe0 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e  .** reflected in
12ff0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
13000 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
13010 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71 6c  rcode()] or [sql
13020 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
13030 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
13040 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 31 7d  :.**.** {H12371}
13050 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 67   If a [sqlite3_g
13060 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61 69 6c  et_table()] fail
13070 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  s a memory alloc
13080 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20  ation, then.**  
13090 20 20 20 20 20 20 20 20 69 74 20 73 68 61 6c 6c          it shall
130a0 20 66 72 65 65 20 74 68 65 20 72 65 73 75 6c 74   free the result
130b0 20 74 61 62 6c 65 20 75 6e 64 65 72 20 63 6f 6e   table under con
130c0 73 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72 74  struction, abort
130d0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
130e0 20 71 75 65 72 79 20 69 6e 20 70 72 6f 63 65 73   query in proces
130f0 73 2c 20 73 6b 69 70 20 61 6e 79 20 73 75 62 73  s, skip any subs
13100 65 71 75 65 6e 74 20 71 75 65 72 69 65 73 2c 20  equent queries, 
13110 73 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  set the.**      
13120 20 20 20 20 2a 70 61 7a 52 65 73 75 6c 74 20 6f      *pazResult o
13130 75 74 70 75 74 20 70 6f 69 6e 74 65 72 20 74 6f  utput pointer to
13140 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75 72 6e   NULL and return
13150 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
13160 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 33 7d 20  .**.** {H12373} 
13170 49 66 20 74 68 65 20 70 6e 43 6f 6c 75 6d 6e 20  If the pnColumn 
13180 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
13190 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
131a0 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a  )] is not NULL.*
131b0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
131c0 61 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76  a successful inv
131d0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
131e0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
131f0 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20   shall.**       
13200 20 20 20 77 72 69 74 65 20 74 68 65 20 6e 75 6d     write the num
13210 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
13220 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
13230 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20    result set of 
13240 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a  the query into *
13250 70 6e 43 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  pnColumn..**.** 
13260 7b 48 31 32 33 37 34 7d 20 49 66 20 74 68 65 20  {H12374} If the 
13270 70 6e 52 6f 77 20 70 61 72 61 6d 65 74 65 72 20  pnRow parameter 
13280 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  to [sqlite3_get_
13290 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20  table()] is not 
132a0 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  NULL.**         
132b0 20 74 68 65 6e 20 61 20 73 75 63 63 65 73 73 66   then a successf
132c0 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
132d0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
132e0 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20  ble()] shall.** 
132f0 20 20 20 20 20 20 20 20 20 77 72 69 74 65 73 20           writes 
13300 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
13310 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20  ws in the.**    
13320 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74        result set
13330 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 69 6e   of the query in
13340 74 6f 20 2a 70 6e 52 6f 77 2e 0a 2a 2a 0a 2a 2a  to *pnRow..**.**
13350 20 7b 48 31 32 33 37 36 7d 20 41 20 73 75 63 63   {H12376} A succ
13360 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
13370 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65  n of [sqlite3_ge
13380 74 5f 74 61 62 6c 65 28 29 5d 20 74 68 61 74 20  t_table()] that 
13390 63 6f 6d 70 75 74 65 73 0a 2a 2a 20 20 20 20 20  computes.**     
133a0 20 20 20 20 20 4e 20 72 6f 77 73 20 6f 66 20 72       N rows of r
133b0 65 73 75 6c 74 20 77 69 74 68 20 43 20 63 6f 6c  esult with C col
133c0 75 6d 6e 73 20 70 65 72 20 72 6f 77 20 73 68 61  umns per row sha
133d0 6c 6c 20 6d 61 6b 65 20 2a 70 61 7a 52 65 73 75  ll make *pazResu
133e0 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  lt.**          p
133f0 6f 69 6e 74 20 74 6f 20 61 6e 20 61 72 72 61 79  oint to an array
13400 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
13410 28 4e 2b 31 29 2a 43 20 73 74 72 69 6e 67 73 20  (N+1)*C strings 
13420 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 0a  where the first.
13430 2a 2a 20 20 20 20 20 20 20 20 20 20 43 20 73 74  **          C st
13440 72 69 6e 67 73 20 61 72 65 20 63 6f 6c 75 6d 6e  rings are column
13450 20 6e 61 6d 65 73 20 61 73 20 6f 62 74 61 69 6e   names as obtain
13460 65 64 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20  ed from.**      
13470 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
13480 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20  umn_name()] and 
13490 74 68 65 20 72 65 73 74 20 61 72 65 20 63 6f 6c  the rest are col
134a0 75 6d 6e 20 72 65 73 75 6c 74 20 76 61 6c 75 65  umn result value
134b0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62  s.**          ob
134c0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
134d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
134e0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  ()]..**.** {H123
134f0 37 39 7d 20 54 68 65 20 76 61 6c 75 65 73 20 69  79} The values i
13500 6e 20 74 68 65 20 70 61 7a 52 65 73 75 6c 74 20  n the pazResult 
13510 61 72 72 61 79 20 72 65 74 75 72 6e 65 64 20 62  array returned b
13520 79 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  y [sqlite3_get_t
13530 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20  able()].**      
13540 20 20 20 20 73 68 61 6c 6c 20 72 65 6d 61 69 6e      shall remain
13550 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 63 6c 65   valid until cle
13560 61 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ared by [sqlite3
13570 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a  _free_table()]..
13580 2a 2a 0a 2a 2a 20 7b 48 31 32 33 38 32 7d 20 57  **.** {H12382} W
13590 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
135a0 75 72 73 20 64 75 72 69 6e 67 20 65 76 61 6c 75  urs during evalu
135b0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
135c0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a 2a  3_get_table()].*
135d0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 66  *          the f
135e0 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65  unction shall se
135f0 74 20 2a 70 61 7a 52 65 73 75 6c 74 20 74 6f 20  t *pazResult to 
13600 4e 55 4c 4c 2c 20 77 72 69 74 65 20 61 6e 20 65  NULL, write an e
13610 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20  rror message.** 
13620 20 20 20 20 20 20 20 20 20 69 6e 74 6f 20 6d 65           into me
13630 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
13640 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
13650 6f 63 28 29 5d 2c 20 6d 61 6b 65 0a 2a 2a 20 20  oc()], make.**  
13660 20 20 20 20 20 20 20 20 2a 2a 70 7a 45 72 72 6d          **pzErrm
13670 73 67 20 70 6f 69 6e 74 20 74 6f 20 74 68 61 74  sg point to that
13680 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2c 20   error message, 
13690 61 6e 64 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  and return a.** 
136a0 20 20 20 20 20 20 20 20 20 61 70 70 72 6f 70 72           appropr
136b0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
136c0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
136d0 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73  3_get_table(.  s
136e0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
136f0 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
13700 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
13710 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
13720 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
13730 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
13740 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c  char ***pazResul
13750 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73  t,    /* Results
13760 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f   of the query */
13770 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20  .  int *pnRow,  
13780 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
13790 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77  er of result row
137a0 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
137b0 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d  /.  int *pnColum
137c0 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d  n,        /* Num
137d0 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  ber of result co
137e0 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65  lumns written he
137f0 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70  re */.  char **p
13800 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a  zErrmsg       /*
13810 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
13820 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f  en here */.);.vo
13830 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  id sqlite3_free_
13840 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
13850 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
13860 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
13870 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
13880 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34   Functions {H174
13890 30 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 30  00} <S70000><S20
138a0 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  000>.**.** These
138b0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
138c0 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  rkalikes of the 
138d0 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
138e0 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
138f0 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
13900 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
13910 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
13920 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
13930 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
13940 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
13950 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
13960 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
13970 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
13980 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
13990 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
139a0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
139b0 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
139c0 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
139d0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
139e0 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72  free()].  Both r
139f0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
13a00 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
13a10 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
13a20 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
13a30 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
13a40 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
13a50 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
13a60 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
13a70 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70  * In sqlite3_snp
13a80 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
13a90 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
13aa0 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
13ab0 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
13ac0 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
13ad0 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
13ae0 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
13af0 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
13b00 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
13b10 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
13b20 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
13b30 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
13b40 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
13b50 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
13b60 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
13b70 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
13b80 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
13b90 66 28 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e  f().  This is an
13ba0 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
13bb0 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
13bc0 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
13bd0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
13be0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
13bf0 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20  tibility.  Note 
13c00 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
13c10 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
13c20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
13c30 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
13c40 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
13c50 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
13c60 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
13c70 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
13c80 20 62 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d   buffer.  We adm
13c90 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
13ca0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
13cb0 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
13cc0 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
13cd0 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
13ce0 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
13cf0 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
13d00 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
13d10 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
13d20 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
13d30 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
13d40 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73  bility..**.** As
13d50 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
13d60 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
13d70 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
13d80 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
13d90 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
13da0 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
13db0 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
13dc0 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20  erminated.  The 
13dd0 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
13de0 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
13df0 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
13e00 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
13e10 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
13e20 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
13e30 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
13e40 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
13e50 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
13e60 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
13e70 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
13e80 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ers..**.** These
13e90 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
13ea0 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
13eb0 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
13ec0 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
13ed0 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
13ee0 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
13ef0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
13f00 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
13f10 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
13f20 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
13f30 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
13f40 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
13f50 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
13f60 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
13f70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f  ..**.** The %q o
13f80 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
13f90 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
13fa0 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
13fb0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
13fc0 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
13fd0 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
13fe0 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
13ff0 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
14000 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
14010 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
14020 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
14030 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79  ing literal.  By
14040 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27   doubling each '
14050 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  \''.** character
14060 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74   it escapes that
14070 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61   character and a
14080 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69  llows it to be i
14090 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20  nserted into.** 
140a0 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  the string..**.*
140b0 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61  * For example, a
140c0 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67  ssume the string
140d0 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20   variable zText 
140e0 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73  contains text as
140f0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
14100 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
14110 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78  >.**  char *zTex
14120 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70  t = "It's a happ
14130 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72  y day!";.** </pr
14140 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
14150 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73  **.** One can us
14160 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61  e this text in a
14170 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
14180 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
14190 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
141a0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
141b0 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
141c0 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
141d0 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27  O table VALUES('
141e0 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  %q')", zText);.*
141f0 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
14200 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
14210 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
14220 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
14230 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
14240 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  e>.**.** Because
14250 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73   the %q format s
14260 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  tring is used, t
14270 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  he '\'' characte
14280 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73  r in zText.** is
14290 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65   escaped and the
142a0 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69   SQL generated i
142b0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
142c0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
142d0 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
142e0 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
142f0 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70  UES('It''s a hap
14300 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70  py day!').** </p
14310 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
14320 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63  .**.** This is c
14330 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20  orrect.  Had we 
14340 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20  used %s instead 
14350 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72  of %q, the gener
14360 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c  ated SQL.** woul
14370 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69  d have looked li
14380 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
14390 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
143a0 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
143b0 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
143c0 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
143d0 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  !');.** </pre></
143e0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
143f0 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78  * This second ex
14400 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20  ample is an SQL 
14410 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41  syntax error.  A
14420 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65  s a general rule
14430 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61   you should.** a
14440 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73  lways use %q ins
14450 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20  tead of %s when 
14460 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69  inserting text i
14470 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74  nto a string lit
14480 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eral..**.** The 
14490 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
144a0 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
144b0 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
144c0 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
144d0 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
144e0 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
144f0 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
14500 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
14510 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61  eter in the.** a
14520 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20  rgument list is 
14530 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
14540 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
14550 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
14560 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c  without.** singl
14570 65 20 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61  e quotes) in pla
14580 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74  ce of the %Q opt
14590 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ion.  So, for ex
145a0 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
145b0 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
145c0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
145d0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
145e0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
145f0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
14600 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
14610 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
14620 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
14630 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
14640 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
14650 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
14660 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
14670 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
14680 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
14690 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
146a0 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
146b0 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
146c0 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
146d0 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
146e0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
146f0 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
14700 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
14710 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25   exactly like "%
14720 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  s" with the.** a
14730 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
14740 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
14750 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
14760 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
14770 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
14780 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
14790 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
147a0 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d  ut string. {END}
147b0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
147c0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 33  S:.**.** {H17403
147d0 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
147e0 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b  mprintf()] and [
147f0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
14800 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ()] interfaces.*
14810 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75  *           retu
14820 72 6e 20 65 69 74 68 65 72 20 70 6f 69 6e 74 65  rn either pointe
14830 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
14840 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
14850 6e 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20  ngs held in.**  
14860 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20           memory 
14870 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
14880 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
14890 20 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   or NULL pointer
148a0 73 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  s if.**         
148b0 20 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c    a call to [sql
148c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
148d0 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  ails..**.** {H17
148e0 34 30 36 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  406}  The [sqlit
148f0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
14900 6e 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20  nterface writes 
14910 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
14920 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 55  d.**           U
14930 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e 74 6f  TF-8 string into
14940 20 74 68 65 20 62 75 66 66 65 72 20 70 6f 69 6e   the buffer poin
14950 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 73 65  ted to by the se
14960 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
14970 2a 20 20 20 20 20 20 20 20 20 20 20 70 72 6f 76  *           prov
14980 69 64 65 64 20 74 68 61 74 20 74 68 65 20 66 69  ided that the fi
14990 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
149a0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
149b0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30  ro..**.** {H1740
149c0 37 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  7}  The [sqlite3
149d0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74  _snprintf()] int
149e0 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
149f0 77 72 69 74 65 20 73 6c 6f 74 73 20 6f 66 0a 2a  write slots of.*
14a00 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 73 20  *           its 
14a10 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 28 74  output buffer (t
14a20 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
14a30 74 65 72 29 20 6f 75 74 73 69 64 65 20 74 68 65  ter) outside the
14a40 20 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20   range.**       
14a50 20 20 20 20 6f 66 20 30 20 74 68 72 6f 75 67 68      of 0 through
14a60 20 4e 2d 31 20 28 77 68 65 72 65 20 4e 20 69 73   N-1 (where N is
14a70 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
14a80 65 74 65 72 29 0a 2a 2a 20 20 20 20 20 20 20 20  eter).**        
14a90 20 20 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66     regardless of
14aa0 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
14ab0 68 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  he string.**    
14ac0 20 20 20 20 20 20 20 72 65 71 75 65 73 74 65 64         requested
14ad0 20 62 79 20 74 68 65 20 66 6f 72 6d 61 74 20 73   by the format s
14ae0 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2f  pecification..*/
14af0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d  .char *sqlite3_m
14b00 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
14b10 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73  r*,...);.char *s
14b20 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
14b30 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
14b40 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c  list);.char *sql
14b50 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e  ite3_snprintf(in
14b60 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
14b70 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  ar*, ...);../*.*
14b80 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
14b90 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
14ba0 62 73 79 73 74 65 6d 20 7b 48 31 37 33 30 30 7d  bsystem {H17300}
14bb0 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20000>.**.** 
14bc0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
14bd0 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
14be0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
14bf0 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
14c00 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
14c10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
14c20 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
14c30 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
14c40 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
14c50 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
14c60 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
14c70 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
14c80 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
14c90 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
14ca0 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
14cb0 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
14cc0 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
14cd0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
14ce0 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
14cf0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
14d00 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
14d10 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
14d20 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
14d30 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
14d40 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
14d50 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d  .** If sqlite3_m
14d60 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
14d70 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
14d80 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
14d90 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
14da0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
14db0 2e 20 20 49 66 20 74 68 65 20 70 61 72 61 6d 65  .  If the parame
14dc0 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
14dd0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
14de0 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
14df0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
14e00 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
14e10 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
14e20 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20  ..**.** Calling 
14e30 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77  sqlite3_free() w
14e40 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72  ith a pointer pr
14e50 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
14e60 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
14e70 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
14e80 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
14e90 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f  leases that memo
14ea0 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74  ry so.** that it
14eb0 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64   might be reused
14ec0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66  .  The sqlite3_f
14ed0 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
14ee0 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
14ef0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
14f00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
14f10 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
14f20 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
14f30 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
14f40 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
14f50 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
14f60 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
14f70 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
14f80 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
14f90 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
14fa0 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
14fb0 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
14fc0 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
14fd0 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
14fe0 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
14ff0 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
15000 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
15010 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
15020 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
15030 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
15040 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
15050 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
15060 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
15070 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
15080 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
15090 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
150a0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 66  c() or sqlite3_f
150b0 72 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ree()..**.** The
150c0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
150d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
150e0 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20  empts to resize 
150f0 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72  a.** prior memor
15100 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
15110 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
15120 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20  tes, where N is 
15130 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  the.** second pa
15140 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65  rameter.  The me
15150 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
15160 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73  to be resized is
15170 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61   the first.** pa
15180 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74 68 65  rameter.  If the
15190 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
151a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
151b0 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
151c0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
151d0 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
151e0 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
151f0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
15200 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
15210 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
15220 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
15230 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
15240 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64  ** If the second
15250 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
15260 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
15270 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
15280 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
15290 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
152a0 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
152b0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
152c0 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65  e3_free(P) where
152d0 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20   P is the first 
152e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
152f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
15300 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ** sqlite3_reall
15310 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  oc() returns a p
15320 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
15330 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
15340 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
15350 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
15360 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65  NULL if sufficie
15370 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61  nt memory is una
15380 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20  vailable..** If 
15390 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
153a0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
153b0 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
153c0 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
153d0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
153e0 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
153f0 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
15400 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
15410 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
15420 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61  ite3_realloc() a
15430 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
15440 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
15450 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f  ..** If sqlite3_
15460 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
15470 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  s NULL, then the
15480 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
15490 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65  n.** is not free
154a0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d  d..**.** The mem
154b0 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
154c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
154d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
154e0 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77  lloc().** is alw
154f0 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
15500 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
15510 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44  e boundary. {END
15520 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  }.**.** The defa
15530 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ult implementati
15540 6f 6e 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79  on of the memory
15550 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
15560 79 73 74 65 6d 20 75 73 65 73 0a 2a 2a 20 74 68  ystem uses.** th
15570 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c  e malloc(), real
15580 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
15590 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
155a0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
155b0 61 72 79 2e 0a 2a 2a 20 7b 48 31 37 33 38 32 7d  ary..** {H17382}
155c0 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c   However, if SQL
155d0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
155e0 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
155f0 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c  TE_MEMORY_SIZE=<
15600 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72 65 70  i>NNN</i> C prep
15610 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 28  rocessor macro (
15620 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e  where <i>NNN</i>
15630 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65  .** is an intege
15640 72 29 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  r), then SQLite 
15650 63 72 65 61 74 65 20 61 20 73 74 61 74 69 63 20  create a static 
15660 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65 61 73  array of at leas
15670 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20  t.** <i>NNN</i> 
15680 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
15690 64 20 75 73 65 73 20 74 68 61 74 20 61 72 72 61  d uses that arra
156a0 79 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  y for all of its
156b0 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d 6f   dynamic.** memo
156c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
156d0 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64 69  eds. {END}  Addi
156e0 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  tional memory al
156f0 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73 0a  locator options.
15700 2a 2a 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ** may be added 
15710 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
15720 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  es..**.** In SQL
15730 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
15740 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
15750 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
15760 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
15770 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
15780 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
15790 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
157a0 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
157b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
157c0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
157d0 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
157e0 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
157f0 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
15800 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
15810 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
15820 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
15830 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   used..**.** The
15840 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
15850 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
15860 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  s.** the system 
15870 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
15880 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
15890 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
158a0 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
158b0 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
158c0 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
158d0 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
158e0 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
158f0 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
15900 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
15910 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
15920 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
15930 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
15940 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64 2c  rs are detected,
15950 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65   but.** they are
15960 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
15970 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
15980 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
15990 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
159a0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
159b0 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  EM]..**.** INVAR
159c0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
159d0 37 33 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69  7303}  The [sqli
159e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69  te3_malloc(N)] i
159f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
15a00 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65   either a pointe
15a10 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
15a20 20 20 61 20 6e 65 77 6c 79 20 63 68 65 63 6b 65    a newly checke
15a30 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 6f 66 20 61  d-out block of a
15a40 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
15a50 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20  of memory.**    
15a60 20 20 20 20 20 20 20 74 68 61 74 20 69 73 20 38         that is 8
15a70 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f  -byte aligned, o
15a80 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  r it returns NUL
15a90 4c 20 69 66 20 69 74 20 69 73 20 75 6e 61 62 6c  L if it is unabl
15aa0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  e.**           t
15ab0 6f 20 66 75 6c 66 69 6c 6c 20 74 68 65 20 72 65  o fulfill the re
15ac0 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  quest..**.** {H1
15ad0 37 33 30 34 7d 20 20 54 68 65 20 5b 73 71 6c 69  7304}  The [sqli
15ae0 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69  te3_malloc(N)] i
15af0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
15b00 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
15b10 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  if.**           
15b20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
15b30 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2e  r equal to zero.
15b40 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 35 7d 20  .**.** {H17305} 
15b50 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 72   The [sqlite3_fr
15b60 65 65 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ee(P)] interface
15b70 20 72 65 6c 65 61 73 65 73 20 6d 65 6d 6f 72 79   releases memory
15b80 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20   previously.**  
15b90 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 65           returne
15ba0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
15bb0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
15bc0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
15bd0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d  ,.**           m
15be0 61 6b 69 6e 67 20 69 74 20 61 76 61 69 6c 61 62  aking it availab
15bf0 6c 65 20 66 6f 72 20 72 65 75 73 65 2e 0a 2a 2a  le for reuse..**
15c00 0a 2a 2a 20 7b 48 31 37 33 30 36 7d 20 20 41 20  .** {H17306}  A 
15c10 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
15c20 5f 66 72 65 65 28 4e 55 4c 4c 29 5d 20 69 73 20  _free(NULL)] is 
15c30 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
15c40 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 30 7d  ..**.** {H17310}
15c50 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c    A call to [sql
15c60 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 30 2c 4e  ite3_realloc(0,N
15c70 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  )] is equivalent
15c80 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20   to a call.**   
15c90 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69          to [sqli
15ca0 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 2e 0a  te3_malloc(N)]..
15cb0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 32 7d 20 20  **.** {H17312}  
15cc0 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
15cd0 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 30 29 5d  e3_realloc(P,0)]
15ce0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
15cf0 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20  o a call.**     
15d00 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65        to [sqlite
15d10 33 5f 66 72 65 65 28 50 29 5d 2e 0a 2a 2a 0a 2a  3_free(P)]..**.*
15d20 2a 20 7b 48 31 37 33 31 35 7d 20 20 54 68 65 20  * {H17315}  The 
15d30 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
15d40 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15d50 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  ()], [sqlite3_re
15d60 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20  alloc()],.**    
15d70 20 20 20 20 20 20 20 61 6e 64 20 5b 73 71 6c 69         and [sqli
15d80 74 65 33 5f 66 72 65 65 28 29 5d 20 66 6f 72 20  te3_free()] for 
15d90 61 6c 6c 20 6f 66 20 69 74 73 20 6d 65 6d 6f 72  all of its memor
15da0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 6e 64  y allocation and
15db0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 64 65  .**           de
15dc0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
15dd0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 38 7d  ..**.** {H17318}
15de0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72    The [sqlite3_r
15df0 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69 6e 74  ealloc(P,N)] int
15e00 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
15e10 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65 72 0a  ither a pointer.
15e20 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20  **           to 
15e30 61 20 62 6c 6f 63 6b 20 6f 66 20 63 68 65 63 6b  a block of check
15e40 65 64 2d 6f 75 74 20 6d 65 6d 6f 72 79 20 6f 66  ed-out memory of
15e50 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
15e60 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20 20 20 20  s in size.**    
15e70 20 20 20 20 20 20 20 74 68 61 74 20 69 73 20 38         that is 8
15e80 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f  -byte aligned, o
15e90 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
15ea0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 31 7d  ..**.** {H17321}
15eb0 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    When [sqlite3_
15ec0 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65  realloc(P,N)] re
15ed0 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  turns a non-NULL
15ee0 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72   pointer, it fir
15ef0 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  st.**           
15f00 63 6f 70 69 65 73 20 74 68 65 20 66 69 72 73 74  copies the first
15f10 20 4b 20 62 79 74 65 73 20 6f 66 20 63 6f 6e 74   K bytes of cont
15f20 65 6e 74 20 66 72 6f 6d 20 50 20 69 6e 74 6f 20  ent from P into 
15f30 74 68 65 20 6e 65 77 6c 79 0a 2a 2a 20 20 20 20  the newly.**    
15f40 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 64         allocated
15f50 20 62 6c 6f 63 6b 2c 20 77 68 65 72 65 20 4b 20   block, where K 
15f60 69 73 20 74 68 65 20 6c 65 73 73 65 72 20 6f 66  is the lesser of
15f70 20 4e 20 61 6e 64 20 74 68 65 20 73 69 7a 65 20   N and the size 
15f80 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  of.**           
15f90 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  the buffer P..**
15fa0 0a 2a 2a 20 7b 48 31 37 33 32 32 7d 20 20 57 68  .** {H17322}  Wh
15fb0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  en [sqlite3_real
15fc0 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e  loc(P,N)] return
15fd0 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
15fe0 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a  nter, it first.*
15ff0 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 6c 65  *           rele
16000 61 73 65 73 20 74 68 65 20 62 75 66 66 65 72 20  ases the buffer 
16010 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 33  P..**.** {H17323
16020 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  }  When [sqlite3
16030 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72  _realloc(P,N)] r
16040 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
16050 20 62 75 66 66 65 72 20 50 20 69 73 0a 2a 2a 20   buffer P is.** 
16060 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 6d 6f            not mo
16070 64 69 66 69 65 64 20 6f 72 20 72 65 6c 65 61 73  dified or releas
16080 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50  ed..**.** ASSUMP
16090 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
160a0 37 33 35 30 7d 20 20 54 68 65 20 70 6f 69 6e 74  7350}  The point
160b0 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
160c0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
160d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
160e0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20 20 20  alloc()].**     
160f0 20 20 20 20 20 20 6d 75 73 74 20 62 65 20 65 69        must be ei
16100 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73  ther NULL or els
16110 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69  e pointers obtai
16120 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
16130 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 6e  .**           in
16140 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
16150 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
16160 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
16170 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
16180 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74  **           not
16190 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
161a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35  ed..**.** {A1735
161b0 31 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  1}  The applicat
161c0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
161d0 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
161e0 61 72 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  art of.**       
161f0 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d      a block of m
16200 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
16210 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
16220 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
16230 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 66 72 65      [sqlite3_fre
16240 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
16250 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  _realloc()]..*/.
16260 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
16270 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
16280 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
16290 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
162a0 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
162b0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
162c0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
162d0 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
162e0 74 69 63 73 20 7b 48 31 37 33 37 30 7d 20 3c 53  tics {H17370} <S
162f0 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c  30210>.**.** SQL
16300 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
16310 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
16320 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
16330 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
16340 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
16350 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
16360 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
16370 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
16380 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
16390 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
163a0 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
163b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
163c0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  system..**.** IN
163d0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
163e0 7b 48 31 37 33 37 31 7d 20 54 68 65 20 5b 73 71  {H17371} The [sq
163f0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
16400 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  d()] routine ret
16410 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
16420 6f 66 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20  of bytes.**     
16430 20 20 20 20 20 6f 66 20 6d 65 6d 6f 72 79 20 63       of memory c
16440 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e  urrently outstan
16450 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62  ding (malloced b
16460 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a  ut not freed)..*
16470 2a 0a 2a 2a 20 7b 48 31 37 33 37 33 7d 20 54 68  *.** {H17373} Th
16480 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
16490 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
164a0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
164b0 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 20 20  he maximum.**   
164c0 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20         value of 
164d0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
164e0 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
164f0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
16500 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 61  k.**          wa
16510 73 20 6c 61 73 74 20 72 65 73 65 74 2e 0a 2a 2a  s last reset..**
16520 0a 2a 2a 20 7b 48 31 37 33 37 34 7d 20 54 68 65  .** {H17374} The
16530 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
16540 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
16550 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
16560 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
16570 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
16580 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
16590 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
165a0 20 20 20 20 20 20 20 20 20 20 61 64 64 65 64 20            added 
165b0 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
165c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
165d0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
165e0 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  oc()],.**       
165f0 20 20 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68     but not overh
16600 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
16610 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
16620 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
16630 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74 69  *          routi
16640 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
16650 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
16660 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  call..**.** {H17
16670 33 37 35 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20  375} The memory 
16680 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20  high-water mark 
16690 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20  is reset to the 
166a0 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
166b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
166c0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
166d0 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
166e0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
166f0 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
16700 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
16710 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
16720 20 74 72 75 65 2e 20 20 54 68 65 20 76 61 6c 75   true.  The valu
16730 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20  e returned.**   
16740 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74         by [sqlit
16750 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
16760 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68  ter(1)] is the h
16770 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
16780 2a 20 20 20 20 20 20 20 20 20 20 70 72 69 6f 72  *          prior
16790 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a   to the reset..*
167a0 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
167b0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
167c0 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74  sed(void);.sqlit
167d0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
167e0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
167f0 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29  r(int resetFlag)
16800 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
16810 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d  F: Pseudo-Random
16820 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f   Number Generato
16830 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32 30 30  r {H17390} <S200
16840 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  00>.**.** SQLite
16850 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
16860 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
16870 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
16880 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
16890 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
168a0 20 72 61 6e 64 6f 6d 20 52 4f 57 49 44 73 20 77   random ROWIDs w
168b0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
168c0 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
168d0 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
168e0 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
168f0 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
16900 20 52 4f 57 49 44 2e 20 20 54 68 65 20 50 52 4e   ROWID.  The PRN
16910 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
16920 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
16930 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
16940 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
16950 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
16960 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
16970 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
16980 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
16990 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
169a0 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
169b0 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74  *.** A call to t
169c0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
169d0 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
169e0 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
169f0 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68  ffer P..**.** Th
16a00 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69  e first time thi
16a10 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76  s routine is inv
16a20 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74  oked (either int
16a30 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a  ernally or by.**
16a40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
16a50 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65  ) the PRNG is se
16a60 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f  eded using rando
16a70 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mness obtained.*
16a80 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  * from the xRand
16a90 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
16aa0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
16ab0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
16ac0 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62  t..** On all sub
16ad0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
16ae0 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d  ons, the pseudo-
16af0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
16b00 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
16b10 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
16b20 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
16b30 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
16b40 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
16b50 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ethod..**.** INV
16b60 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
16b70 48 31 37 33 39 32 7d 20 54 68 65 20 5b 73 71 6c  H17392} The [sql
16b80 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
16b90 4e 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  N,P)] interface 
16ba0 77 72 69 74 65 73 20 4e 20 62 79 74 65 73 20 6f  writes N bytes o
16bb0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 69  f.**          hi
16bc0 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
16bd0 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  o-randomness int
16be0 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a 76  o buffer P..*/.v
16bf0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64  oid sqlite3_rand
16c00 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f  omness(int N, vo
16c10 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id *P);../*.** C
16c20 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
16c30 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
16c40 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48  ion Callbacks {H
16c50 31 32 35 30 30 7d 20 3c 53 37 30 31 30 30 3e 0a  12500} <S70100>.
16c60 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
16c70 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 20 61  ne registers a a
16c80 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
16c90 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ck with a partic
16ca0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
16cb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73  e connection], s
16cc0 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66  upplied in the f
16cd0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
16ce0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
16cf0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
16d00 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
16d10 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
16d20 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
16d30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
16d40 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
16d50 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
16d60 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
16d70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
16d80 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
16d90 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
16da0 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a  ].  At various.*
16db0 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
16dc0 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
16dd0 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
16de0 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
16df0 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
16e00 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
16e10 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
16e20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
16e30 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
16e40 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
16e50 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68  are allowed.  Th
16e60 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16e70 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
16e80 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
16e90 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
16ea0 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
16eb0 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
16ec0 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
16ed0 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
16ee0 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
16ef0 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
16f00 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
16f10 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
16f20 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
16f30 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
16f40 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
16f50 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
16f60 61 6e 20 65 72 72 6f 72 2e 20 20 49 66 20 74 68  an error.  If th
16f70 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16f80 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
16f90 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
16fa0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
16fb0 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
16fc0 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
16fd0 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
16fe0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
16ff0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
17000 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
17010 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
17020 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
17030 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
17040 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
17050 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
17060 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
17070 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
17080 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
17090 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
170a0 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65  is ok.  When the
170b0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
170c0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
170d0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
170e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
170f0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
17100 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
17110 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
17120 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
17130 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
17140 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
17150 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
17160 64 65 6e 69 65 64 2e 20 20 49 66 20 74 68 65 20  denied.  If the 
17170 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20  authorizer code 
17180 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
17190 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
171a0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
171b0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
171c0 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
171d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
171e0 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
171f0 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
17200 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
17210 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
17220 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
17230 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
17240 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
17250 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
17260 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
17270 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
17280 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
17290 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
172a0 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
172b0 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
172c0 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
172d0 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
172e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
172f0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
17300 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
17310 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
17320 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
17330 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
17340 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
17350 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
17360 66 61 63 65 2e 20 54 68 65 20 73 65 63 6f 6e 64  face. The second
17370 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
17380 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
17390 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
173a0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
173b0 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
173c0 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
173d0 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
173e0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
173f0 2e 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f  . The third thro
17400 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
17410 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
17420 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
17430 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
17440 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
17450 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
17460 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
17470 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
17480 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
17490 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
174a0 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
174b0 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
174c0 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
174d0 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
174e0 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
174f0 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
17500 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
17510 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
17520 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
17530 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
17540 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
17550 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
17560 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
17570 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
17580 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
17590 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
175a0 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
175b0 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
175c0 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
175d0 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
175e0 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
175f0 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
17600 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
17610 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
17620 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
17630 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
17640 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
17650 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
17660 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
17670 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
17680 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
17690 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
176a0 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
176b0 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
176c0 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
176d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
176e0 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
176f0 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
17700 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
17710 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
17720 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
17730 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
17740 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
17750 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
17760 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
17770 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
17780 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
17790 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
177a0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
177b0 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
177c0 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
177d0 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
177e0 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
177f0 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
17800 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
17810 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
17820 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
17830 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
17840 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
17850 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17860 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
17870 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
17880 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
17890 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
178a0 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
178b0 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20 74 68  all.  Disable th
178c0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
178d0 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
178e0 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
178f0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
17900 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
17910 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ault..**.** Note
17920 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
17930 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
17940 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
17950 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
17960 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
17970 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
17980 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
17990 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
179a0 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
179b0 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
179c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
179d0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
179e0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 31  S:.**.** {H12501
179f0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  } The [sqlite3_s
17a00 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 44 2c  et_authorizer(D,
17a10 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ...)] interface 
17a20 72 65 67 69 73 74 65 72 73 20 61 0a 2a 2a 20 20  registers a.**  
17a30 20 20 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a          authoriz
17a40 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
17a50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17a60 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tion D..**.** {H
17a70 31 32 35 30 32 7d 20 54 68 65 20 61 75 74 68 6f  12502} The autho
17a80 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
17a90 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
17aa0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a   statements are.
17ab0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 69 6e  **          bein
17ac0 67 20 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  g compiled..**.*
17ad0 2a 20 7b 48 31 32 35 30 33 7d 20 49 66 20 74 68  * {H12503} If th
17ae0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
17af0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 6e  lback returns an
17b00 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
17b10 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  an.**          [
17b20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
17b30 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
17b40 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
17b50 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
17b60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
17b70 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
17b80 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
17b90 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 20 20 20  at caused.**    
17ba0 20 20 20 20 20 20 74 68 65 20 61 75 74 68 6f 72        the author
17bb0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f  izer callback to
17bc0 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 20   run shall fail 
17bd0 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20  with an.**      
17be0 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f      [SQLITE_ERRO
17bf0 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  R] error code an
17c00 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  d an appropriate
17c10 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
17c20 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 34 7d 20 57  **.** {H12504} W
17c30 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hen the authoriz
17c40 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
17c50 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
17c60 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
17c70 2a 20 20 20 20 20 20 20 20 20 20 64 65 73 63 72  *          descr
17c80 69 62 65 64 20 69 73 20 70 72 6f 63 65 73 73 65  ibed is processe
17c90 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a  d normally..**.*
17ca0 2a 20 7b 48 31 32 35 30 35 7d 20 57 68 65 6e 20  * {H12505} When 
17cb0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
17cc0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
17cd0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
17ce0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
17cf0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
17d00 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
17d10 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 63 61  ent call that ca
17d20 75 73 65 64 20 74 68 65 0a 2a 2a 20 20 20 20 20  used the.**     
17d30 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20       authorizer 
17d40 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20  callback to run 
17d50 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20 20  shall fail.**   
17d60 20 20 20 20 20 20 20 77 69 74 68 20 61 6e 20 5b         with an [
17d70 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72  SQLITE_ERROR] er
17d80 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20  ror code and an 
17d90 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
17da0 20 20 20 20 20 20 20 20 20 20 65 78 70 6c 61 69            explai
17db0 6e 69 6e 67 20 74 68 61 74 20 61 63 63 65 73 73  ning that access
17dc0 20 69 73 20 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a   is denied..**.*
17dd0 2a 20 7b 48 31 32 35 30 36 7d 20 49 66 20 74 68  * {H12506} If th
17de0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64  e authorizer cod
17df0 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d  e (the 2nd param
17e00 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
17e10 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20  orizer.**       
17e20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20     callback) is 
17e30 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 6e  [SQLITE_READ] an
17e40 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
17e50 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
17e60 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  s.**          [S
17e70 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 74  QLITE_IGNORE], t
17e80 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65 64  hen the prepared
17e90 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f   statement is co
17ea0 6e 73 74 72 75 63 74 65 64 20 74 6f 0a 2a 2a 20  nstructed to.** 
17eb0 20 20 20 20 20 20 20 20 20 69 6e 73 65 72 74 20           insert 
17ec0 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
17ed0 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
17ee0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
17ef0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 20 20 20  ould have.**    
17f00 20 20 20 20 20 20 62 65 65 6e 20 72 65 61 64 20        been read 
17f10 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
17f20 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
17f30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 37 7d  ..**.** {H12507}
17f40 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
17f50 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e 64  er code (the 2nd
17f60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
17f70 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20  e authorizer.** 
17f80 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63           callbac
17f90 6b 29 20 69 73 20 61 6e 79 74 68 69 6e 67 20 6f  k) is anything o
17fa0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
17fb0 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a  E_READ], then.**
17fc0 20 20 20 20 20 20 20 20 20 20 61 20 72 65 74 75            a retu
17fd0 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 47  rn of [SQLITE_IG
17fe0 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 20 73 61  NORE] has the sa
17ff0 6d 65 20 65 66 66 65 63 74 20 61 73 20 5b 53 51  me effect as [SQ
18000 4c 49 54 45 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a 2a  LITE_DENY]..**.*
18010 2a 20 7b 48 31 32 35 31 30 7d 20 54 68 65 20 66  * {H12510} The f
18020 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
18030 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
18040 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
18050 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  opy of.**       
18060 20 20 20 74 68 65 20 74 68 69 72 64 20 70 61 72     the third par
18070 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
18080 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
18090 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
180a0 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31  ce..**.** {H1251
180b0 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  1} The second pa
180c0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
180d0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
180e0 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  teger.**        
180f0 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c    [SQLITE_COPY |
18100 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
18110 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
18120 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
18130 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  on.**          t
18140 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
18150 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 32 7d 20  .**.** {H12512} 
18160 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
18170 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
18180 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  rs to the callba
18190 63 6b 20 61 72 65 0a 2a 2a 20 20 20 20 20 20 20  ck are.**       
181a0 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74     zero-terminat
181b0 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
181c0 63 6f 6e 74 61 69 6e 0a 2a 2a 20 20 20 20 20 20  contain.**      
181d0 20 20 20 20 61 64 64 69 74 69 6f 6e 61 6c 20 64      additional d
181e0 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
181f0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
18200 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
18210 7b 48 31 32 35 32 30 7d 20 45 61 63 68 20 63 61  {H12520} Each ca
18220 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
18230 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
18240 20 6f 76 65 72 72 69 64 65 73 0a 2a 2a 20 20 20   overrides.**   
18250 20 20 20 20 20 20 20 61 6e 79 20 70 72 65 76 69         any previ
18260 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c 65 64 20  ously installed 
18270 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
18280 2a 20 7b 48 31 32 35 32 31 7d 20 41 20 4e 55 4c  * {H12521} A NUL
18290 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d 65 61  L authorizer mea
182a0 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74 68 6f  ns that no autho
182b0 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  rization.**     
182c0 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 69 73       callback is
182d0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
182e0 7b 48 31 32 35 32 32 7d 20 54 68 65 20 64 65 66  {H12522} The def
182f0 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 72 20  ault authorizer 
18300 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  is NULL..*/.int 
18310 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
18320 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
18330 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
18340 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
18350 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
18360 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
18370 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
18380 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
18390 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
183a0 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
183b0 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b 48 31  Return Codes {H1
183c0 32 35 39 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a  2590} <H12500>.*
183d0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
183e0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
183f0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
18400 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
18410 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
18420 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
18430 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
18440 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
18450 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
18460 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
18470 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
18480 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
18490 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
184a0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
184b0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
184c0 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
184d0 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
184e0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
184f0 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ion..*/.#define 
18500 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20  SQLITE_DENY   1 
18510 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53    /* Abort the S
18520 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  QL statement wit
18530 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64  h an error */.#d
18540 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e  efine SQLITE_IGN
18550 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74  ORE 2   /* Don't
18560 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62   allow access, b
18570 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74  ut don't generat
18580 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f  e an error */../
18590 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
185a0 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e  uthorizer Action
185b0 20 43 6f 64 65 73 20 7b 48 31 32 35 35 30 7d 20   Codes {H12550} 
185c0 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H12500>.**.** T
185d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
185e0 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
185f0 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
18600 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
18610 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  ction.** that is
18620 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68   invoked to auth
18630 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51  orize certain SQ
18640 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69  L statement acti
18650 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ons.  The.** sec
18660 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
18670 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
18680 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
18690 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
186a0 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
186b0 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
186c0 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
186d0 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
186e0 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
186f0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
18700 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
18710 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  assed..**.** The
18720 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76  se action code v
18730 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68  alues signify wh
18740 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61  at kind of opera
18750 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a  tion is to be.**
18760 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
18770 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
18780 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
18790 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
187a0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
187b0 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d  on will be param
187c0 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
187d0 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
187e0 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64   of these.** cod
187f0 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68  es is used as th
18800 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18810 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 61 72  er.  The 5th par
18820 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
18830 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18840 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
18850 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
18860 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
18870 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70  ,.** etc.) if ap
18880 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 20 36  plicable.  The 6
18890 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
188a0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
188b0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
188c0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
188d0 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
188e0 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
188f0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
18900 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
18910 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
18920 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
18930 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
18940 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
18950 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a  vel SQL code..**
18960 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
18970 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 31 7d 20 54  **.** {H12551} T
18980 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18990 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 20 20 20  ter to an.**    
189a0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
189b0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
189c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
189d0 61 63 6b 5d 20 69 73 20 61 6c 77 61 79 73 20 61  ack] is always a
189e0 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20  n integer.**    
189f0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f        [SQLITE_CO
18a00 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  PY | authorizer 
18a10 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
18a20 66 69 65 73 20 77 68 61 74 20 61 63 74 69 6f 6e  fies what action
18a30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
18a40 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
18a50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 32 7d  ..**.** {H12552}
18a60 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
18a70 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
18a80 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
18a90 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
18aa0 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
18ab0 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 5d  zation callback]
18ac0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c  .**          wil
18ad0 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
18ae0 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
18af0 67 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 20 20  g on which.**   
18b00 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43         [SQLITE_C
18b10 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  OPY | authorizer
18b20 20 63 6f 64 65 5d 20 69 73 20 75 73 65 64 20 61   code] is used a
18b30 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
18b40 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ameter..**.** {H
18b50 31 32 35 35 33 7d 20 54 68 65 20 35 74 68 20 70  12553} The 5th p
18b60 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
18b70 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
18b80 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
18b90 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
18ba0 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74 68   callback] is th
18bb0 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e name.**       
18bc0 20 20 20 6f 66 20 74 68 65 20 64 61 74 61 62 61     of the databa
18bd0 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d 61  se (example: "ma
18be0 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65 74 63  in", "temp", etc
18bf0 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
18c00 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 34 7d  ..**.** {H12554}
18c10 20 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74   The 6th paramet
18c20 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  er to the.**    
18c30 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
18c40 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
18c50 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18c60 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d 65  ack] is the name
18c70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
18c80 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
18c90 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
18ca0 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
18cb0 6c 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  le for.**       
18cc0 20 20 20 74 68 65 20 61 63 63 65 73 73 20 61 74     the access at
18cd0 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
18ce0 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
18cf0 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
18d00 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20   from.**        
18d10 20 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20    top-level SQL 
18d20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
18d30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18d40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18d50 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
18d60 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
18d70 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
18d80 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
18d90 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
18da0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
18db0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
18dc0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18dd0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
18de0 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
18df0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
18e00 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
18e10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18e20 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
18e30 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
18e40 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
18e50 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
18e60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18e70 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
18e80 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
18e90 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18ea0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18eb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18ec0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
18ed0 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
18ee0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
18ef0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18f00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18f10 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
18f20 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
18f30 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
18f40 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18f50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18f60 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
18f70 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
18f80 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
18f90 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
18fa0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18fb0 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
18fc0 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
18fd0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
18fe0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18ff0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19000 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
19010 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
19020 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
19030 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
19040 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
19050 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
19060 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
19070 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
19080 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
19090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
190a0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
190b0 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
190c0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
190d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
190e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
190f0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
19100 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
19110 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
19120 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
19130 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
19140 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
19150 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
19160 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
19170 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19180 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
19190 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
191a0 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
191b0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
191c0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
191d0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
191e0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
191f0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
19200 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
19210 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19220 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
19230 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
19240 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
19250 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
19260 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19270 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
19280 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
19290 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
192a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
192b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
192c0 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
192d0 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
192e0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
192f0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
19300 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19310 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
19320 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
19330 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
19340 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
19350 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
19360 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
19370 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
19380 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19390 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
193a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
193b0 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
193c0 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
193d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
193e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
193f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19400 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
19410 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4e         22   /* N
19420 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
19430 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
19440 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19450 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
19460 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
19470 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
19480 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
19490 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
194a0 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
194b0 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
194c0 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
194d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
194e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
194f0 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
19500 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
19510 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
19520 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
19530 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
19540 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
19550 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
19560 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
19570 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
19580 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
19590 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
195a0 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
195b0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
195c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
195d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
195e0 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
195f0 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
19600 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
19610 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
19620 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
19630 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
19640 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
19650 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
19660 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
19670 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
19680 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
19690 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
196a0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
196b0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
196c0 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
196d0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
196e0 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e     /* Function N
196f0 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
19700 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19710 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
19720 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
19730 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
19740 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
19750 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
19760 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
19770 6e 63 74 69 6f 6e 73 20 7b 48 31 32 32 38 30 7d  nctions {H12280}
19780 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 20 45 58 50   <S60400>.** EXP
19790 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
197a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
197b0 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
197c0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
197d0 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
197e0 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
197f0 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
19800 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
19810 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
19820 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
19830 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
19840 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
19850 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
19860 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
19870 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
19880 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
19890 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
198a0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68  3_step()]..** Th
198b0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
198c0 6e 73 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  ns a UTF-8 rende
198d0 72 69 6e 67 20 6f 66 20 74 68 65 20 53 51 4c 20  ring of the SQL 
198e0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a  statement text.*
198f0 2a 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  * as the stateme
19900 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
19910 65 78 65 63 75 74 69 6e 67 2e 20 20 41 64 64 69  executing.  Addi
19920 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  tional callbacks
19930 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63   occur.** as eac
19940 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70  h triggered subp
19950 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65  rogram is entere
19960 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  d.  The callback
19970 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a  s for triggers.*
19980 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d  * contain a UTF-
19990 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68  8 SQL comment th
199a0 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68  at identifies th
199b0 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a  e trigger..**.**
199c0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
199d0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
199e0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
199f0 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
19a00 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
19a10 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
19a20 68 65 73 2e 20 20 54 68 65 20 70 72 6f 66 69 6c  hes.  The profil
19a30 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
19a40 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  ins.** the origi
19a50 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  nal statement te
19a60 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61  xt and an estima
19a70 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  te of wall-clock
19a80 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20   time.** of how 
19a90 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
19aa0 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
19ab0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
19ac0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 31  S:.**.** {H12281
19ad0 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  } The callback f
19ae0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
19af0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 74  ed by [sqlite3_t
19b00 72 61 63 65 28 29 5d 20 69 73 0a 2a 2a 20 20 20  race()] is.**   
19b10 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72 20         whenever 
19b20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
19b30 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f   first begins to
19b40 20 65 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a 20   execute and.** 
19b50 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 65           wheneve
19b60 72 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70  r a trigger subp
19b70 72 6f 67 72 61 6d 20 66 69 72 73 74 20 62 65 67  rogram first beg
19b80 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a  ins to run..**.*
19b90 2a 20 7b 48 31 32 32 38 32 7d 20 45 61 63 68 20  * {H12282} Each 
19ba0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
19bb0 5f 74 72 61 63 65 28 29 5d 20 6f 76 65 72 72 69  _trace()] overri
19bc0 64 65 73 20 74 68 65 20 70 72 65 76 69 6f 75 73  des the previous
19bd0 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ly.**          r
19be0 65 67 69 73 74 65 72 65 64 20 74 72 61 63 65 20  egistered trace 
19bf0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
19c00 7b 48 31 32 32 38 33 7d 20 41 20 4e 55 4c 4c 20  {H12283} A NULL 
19c10 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 64  trace callback d
19c20 69 73 61 62 6c 65 73 20 74 72 61 63 69 6e 67 2e  isables tracing.
19c30 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 34 7d 20  .**.** {H12284} 
19c40 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
19c50 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20  nt to the trace 
19c60 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
19c70 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  py of.**        
19c80 20 20 74 68 65 20 70 6f 69 6e 74 65 72 20 77 68    the pointer wh
19c90 69 63 68 20 77 61 73 20 74 68 65 20 33 72 64 20  ich was the 3rd 
19ca0 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
19cb0 69 74 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a 2a  ite3_trace()]..*
19cc0 2a 0a 2a 2a 20 7b 48 31 32 32 38 35 7d 20 54 68  *.** {H12285} Th
19cd0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
19ce0 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63  t to the trace c
19cf0 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20  allback is a.** 
19d00 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
19d10 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
19d20 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
19d30 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 74 65   the original te
19d40 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  xt.**          o
19d50 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
19d60 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70 61  ent as it was pa
19d70 73 73 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69 74  ssed into [sqlit
19d80 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
19d90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
19da0 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2c 20  the equivalent, 
19db0 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e  or an SQL commen
19dc0 74 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65  t indicating the
19dd0 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20   beginning.**   
19de0 20 20 20 20 20 20 20 6f 66 20 61 20 74 72 69 67         of a trig
19df0 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 0a  ger subprogram..
19e00 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 37 7d 20 54  **.** {H12287} T
19e10 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
19e20 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
19e30 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66  by [sqlite3_prof
19e40 69 6c 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ile()] is invoke
19e50 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  d.**          as
19e60 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
19e70 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a  ent finishes..**
19e80 0a 2a 2a 20 7b 48 31 32 32 38 38 7d 20 54 68 65  .** {H12288} The
19e90 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
19ea0 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20   to the profile 
19eb0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
19ec0 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  py of.**        
19ed0 20 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65    the 3rd parame
19ee0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
19ef0 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  profile()]..**.*
19f00 2a 20 7b 48 31 32 32 38 39 7d 20 54 68 65 20 73  * {H12289} The s
19f10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
19f20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63  to the profile c
19f30 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20  allback is a.** 
19f40 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
19f50 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
19f60 74 72 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61  tring that conta
19f70 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65 74 65  ins the complete
19f80 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20 20   text of.**     
19f90 20 20 20 20 20 74 68 65 20 53 51 4c 20 73 74 61       the SQL sta
19fa0 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73  tement as it was
19fb0 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 5b 73   processed by [s
19fc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
19fd0 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  2()].**         
19fe0 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
19ff0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 39  nt..**.** {H1229
1a000 30 7d 20 54 68 65 20 74 68 69 72 64 20 70 61 72  0} The third par
1a010 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70 72  ameter to the pr
1a020 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69  ofile callback i
1a030 73 20 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a 2a  s an estimate.**
1a040 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
1a050 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73   number of nanos
1a060 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d 63  econds of wall-c
1a070 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71 75 69 72  lock time requir
1a080 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ed to.**        
1a090 20 20 72 75 6e 20 74 68 65 20 53 51 4c 20 73 74    run the SQL st
1a0a0 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74 61  atement from sta
1a0b0 72 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f  rt to finish..*/
1a0c0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74  .void *sqlite3_t
1a0d0 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76  race(sqlite3*, v
1a0e0 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
1a0f0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
1a100 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73   void*);.void *s
1a110 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
1a120 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
1a130 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
1a140 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
1a150 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
1a160 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1a170 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
1a180 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
1a190 20 7b 48 31 32 39 31 30 7d 20 3c 53 36 30 34 30   {H12910} <S6040
1a1a0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
1a1b0 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73  utine configures
1a1c0 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
1a1d0 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72  tion - the.** pr
1a1e0 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
1a1f0 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  - that is invoke
1a200 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
1a210 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75  uring long.** ru
1a220 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b  nning calls to [
1a230 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
1a240 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1a250 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1a260 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20  3_get_table()]. 
1a270 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
1a280 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
1a290 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
1a2a0 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
1a2b0 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
1a2c0 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ery..**.** If th
1a2d0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
1a2e0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
1a2f0 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
1a300 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
1a310 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
1a320 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
1a330 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
1a340 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
1a350 6f 6e 20 6f 6e 20 61 20 47 55 49 20 64 69 61 6c  on on a GUI dial
1a360 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49 4e  og box..**.** IN
1a370 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1a380 7b 48 31 32 39 31 31 7d 20 54 68 65 20 63 61 6c  {H12911} The cal
1a390 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
1a3a0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
1a3b0 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1a3c0 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 20  ndler().**      
1a3d0 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 70      is invoked p
1a3e0 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
1a3f0 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
1a400 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20  calls to.**     
1a410 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74       [sqlite3_st
1a420 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ep()]..**.** {H1
1a430 32 39 31 32 7d 20 54 68 65 20 70 72 6f 67 72 65  2912} The progre
1a440 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  ss callback is i
1a450 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20  nvoked once for 
1a460 65 76 65 72 79 20 4e 20 76 69 72 74 75 61 6c 0a  every N virtual.
1a470 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 61 63 68  **          mach
1a480 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77 68 65  ine opcodes, whe
1a490 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
1a4a0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
1a4b0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
1a4c0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1a4d0 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63 61 6c 6c  _handler()] call
1a4e0 20 74 68 61 74 20 72 65 67 69 73 74 65 72 65 64   that registered
1a4f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1a500 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 4e   callback.  If N
1a510 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31 2c   is less than 1,
1a520 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1a530 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20  s_handler().**  
1a540 20 20 20 20 20 20 20 20 61 63 74 73 20 61 73 20          acts as 
1a550 69 66 20 61 20 4e 55 4c 4c 20 70 72 6f 67 72 65  if a NULL progre
1a560 73 73 20 68 61 6e 64 6c 65 72 20 68 61 64 20 62  ss handler had b
1a570 65 65 6e 20 73 70 65 63 69 66 69 65 64 2e 0a 2a  een specified..*
1a580 2a 0a 2a 2a 20 7b 48 31 32 39 31 33 7d 20 54 68  *.** {H12913} Th
1a590 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
1a5a0 61 63 6b 20 69 74 73 65 6c 66 20 69 73 20 69 64  ack itself is id
1a5b0 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
1a5c0 74 68 69 72 64 0a 2a 2a 20 20 20 20 20 20 20 20  third.**        
1a5d0 20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71    argument to sq
1a5e0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1a5f0 61 6e 64 6c 65 72 28 29 2e 0a 2a 2a 0a 2a 2a 20  andler()..**.** 
1a600 7b 48 31 32 39 31 34 7d 20 54 68 65 20 66 6f 75  {H12914} The fou
1a610 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
1a620 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1a630 5f 68 61 6e 64 6c 65 72 28 29 20 69 73 20 61 0a  _handler() is a.
1a640 2a 2a 20 20 20 20 20 20 20 20 20 20 76 6f 69 64  **          void
1a650 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
1a660 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  to the progress 
1a670 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
1a680 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 65 61       function ea
1a690 63 68 20 74 69 6d 65 20 69 74 20 69 73 20 69 6e  ch time it is in
1a6a0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  voked..**.** {H1
1a6b0 32 39 31 35 7d 20 49 66 20 61 20 63 61 6c 6c 20  2915} If a call 
1a6c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
1a6d0 28 29 5d 20 72 65 73 75 6c 74 73 20 69 6e 20 66  ()] results in f
1a6e0 65 77 65 72 20 74 68 61 6e 20 4e 20 6f 70 63 6f  ewer than N opco
1a6f0 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  des.**          
1a700 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 2c 20  being executed, 
1a710 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73  then the progres
1a720 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65  s callback is ne
1a730 76 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a  ver invoked..**.
1a740 2a 2a 20 7b 48 31 32 39 31 36 7d 20 45 76 65 72  ** {H12916} Ever
1a750 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  y call to [sqlit
1a760 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1a770 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ler()].**       
1a780 20 20 20 6f 76 65 72 77 72 69 74 65 73 20 61 6e     overwrites an
1a790 79 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  y previously reg
1a7a0 69 73 74 65 72 65 64 20 70 72 6f 67 72 65 73 73  istered progress
1a7b0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
1a7c0 7b 48 31 32 39 31 37 7d 20 49 66 20 74 68 65 20  {H12917} If the 
1a7d0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1a7e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
1a7f0 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65  L then no progre
1a800 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  ss.**          h
1a810 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65  andler is invoke
1a820 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 38  d..**.** {H12918
1a830 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73  } If the progres
1a840 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  s callback retur
1a850 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74 68 65  ns a result othe
1a860 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a  r than 0, then.*
1a870 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62  *          the b
1a880 65 68 61 76 69 6f 72 20 69 73 20 61 20 69 66 20  ehavior is a if 
1a890 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
1a8a0 70 74 28 29 5d 20 68 61 64 20 62 65 65 6e 20 63  pt()] had been c
1a8b0 61 6c 6c 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20  alled..**       
1a8c0 20 20 20 3c 53 33 30 35 30 30 3e 0a 2a 2f 0a 76     <S30500>.*/.v
1a8d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  oid sqlite3_prog
1a8e0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c  ress_handler(sql
1a8f0 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28  ite3*, int, int(
1a900 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
1a910 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a920 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65  EF: Opening A Ne
1a930 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  w Database Conne
1a940 63 74 69 6f 6e 20 7b 48 31 32 37 30 30 7d 20 3c  ction {H12700} <
1a950 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S40200>.**.** Th
1a960 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
1a970 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
1a980 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20  base file whose 
1a990 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79  name is given by
1a9a0 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
1a9b0 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 66   argument. The f
1a9c0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1a9d0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1a9e0 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
1a9f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1aa00 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1aa10 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
1aa20 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1aa30 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
1aa40 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
1aa50 36 28 29 2e 20 41 20 5b 64 61 74 61 62 61 73 65  6(). A [database
1aa60 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1aa70 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
1aa80 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
1aa90 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
1aaa0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
1aab0 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
1aac0 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
1aad0 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
1aae0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
1aaf0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
1ab00 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
1ab10 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
1ab20 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
1ab30 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
1ab40 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
1ab50 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
1ab60 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65 20 64  object. If the d
1ab70 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1ab80 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
1ab90 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
1aba0 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
1abb0 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
1abc0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
1abd0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
1abe0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a  returned.  The.*
1abf0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1ac00 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
1ac10 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
1ac20 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
1ac30 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
1ac40 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
1ac50 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
1ac60 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a  f the error..**.
1ac70 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 65  ** The default e
1ac80 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20  ncoding for the 
1ac90 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1aca0 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c   UTF-8 if.** sql
1acb0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1acc0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1acd0 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a   is called and.*
1ace0 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  * UTF-16 in the 
1acf0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1ad00 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  r if sqlite3_ope
1ad10 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a  n16() is used..*
1ad20 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
1ad30 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
1ad40 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
1ad50 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
1ad60 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1ad70 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
1ad80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
1ad90 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
1ada0 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
1adb0 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
1adc0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
1add0 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
1ade0 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
1adf0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
1ae00 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
1ae10 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
1ae20 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
1ae30 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
1ae40 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
1ae50 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
1ae60 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
1ae70 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
1ae80 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
1ae90 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
1aea0 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
1aeb0 72 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  r can take one o
1aec0 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
1aed0 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
1aee0 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
1aef0 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
1af00 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
1af10 4f 4d 55 54 45 58 5d 20 66 6c 61 67 3a 0a 2a 2a  OMUTEX] flag:.**
1af20 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
1af30 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1af40 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
1af50 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1af60 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
1af70 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
1af80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
1af90 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
1afa0 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
1afb0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
1afc0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53  dd>.**.** <dt>[S
1afd0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1afe0 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
1aff0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1b000 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1b010 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
1b020 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
1b030 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
1b040 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
1b050 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
1b060 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
1b070 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
1b080 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
1b090 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
1b0a0 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
1b0b0 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
1b0c0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
1b0d0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c  >.**.** <dt>[SQL
1b0e0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1b0f0 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
1b100 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
1b110 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
1b120 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
1b130 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
1b140 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
1b150 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69  eates it if.** i
1b160 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
1b170 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
1b180 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
1b190 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
1b1a0 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
1b1b0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1b1c0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
1b1d0 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  dd>.** </dl>.**.
1b1e0 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
1b1f0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1b200 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1b210 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
1b220 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
1b230 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e  hown above or on
1b240 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61  e of the combina
1b250 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
1b260 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69  e combined.** wi
1b270 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
1b280 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
1b290 67 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  g, then the beha
1b2a0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
1b2b0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  d..**.** If the 
1b2c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1b2d0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1b2e0 74 2c 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  t, then mutexes 
1b2f0 6f 6e 20 74 68 65 0a 2a 2a 20 6f 70 65 6e 65 64  on the.** opened
1b300 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b310 63 74 69 6f 6e 5d 20 61 72 65 20 64 69 73 61 62  ction] are disab
1b320 6c 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c  led and the appl
1b330 69 61 74 69 6f 6e 20 6d 75 73 74 0a 2a 2a 20 69  iation must.** i
1b340 6e 73 75 72 65 20 74 68 61 74 20 61 63 63 65 73  nsure that acces
1b350 73 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  s to the [databa
1b360 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
1b370 6e 64 20 69 74 73 20 61 73 73 6f 63 69 61 74 65  nd its associate
1b380 64 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  d.** [prepared s
1b390 74 61 74 65 6d 65 6e 74 73 5d 20 69 73 20 73 65  tatements] is se
1b3a0 72 69 61 6c 69 7a 65 64 2e 20 20 54 68 65 20 5b  rialized.  The [
1b3b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1b3c0 54 45 58 5d 20 66 6c 61 67 0a 2a 2a 20 69 73 20  TEX] flag.** is 
1b3d0 74 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  the default beha
1b3e0 76 69 6f 72 20 69 73 20 53 51 4c 69 74 65 20 69  vior is SQLite i
1b3f0 73 20 63 6f 6e 66 69 67 75 72 65 64 20 75 73 69  s configured usi
1b400 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ng the.** [SQLIT
1b410 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
1b420 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45  READ] or [SQLITE
1b430 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
1b440 52 45 41 44 5d 20 6f 70 74 69 6f 6e 73 0a 2a 2a  READ] options.**
1b450 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
1b460 66 69 67 28 29 5d 2e 20 20 54 68 65 20 5b 53 51  fig()].  The [SQ
1b470 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1b480 58 5d 20 66 6c 61 67 20 6f 6e 6c 79 20 6d 61 6b  X] flag only mak
1b490 65 73 20 61 0a 2a 2a 20 64 69 66 66 65 72 65 6e  es a.** differen
1b4a0 63 65 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ce when SQLite i
1b4b0 73 20 69 6e 20 69 74 73 20 64 65 66 61 75 6c 74  s in its default
1b4c0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
1b4d0 53 45 52 49 41 4c 49 5a 45 44 5d 20 6d 6f 64 65  SERIALIZED] mode
1b4e0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  ..**.** If the f
1b4f0 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
1b500 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
1b510 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
1b520 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1b530 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
1b540 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
1b550 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d  tion.  This in-m
1b560 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
1b570 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
1b580 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1b590 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
1b5a0 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
1b5b0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1b5c0 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
1b5d0 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
1b5e0 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
1b5f0 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
1b600 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
1b610 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
1b620 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
1b630 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
1b640 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
1b650 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
1b660 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
1b670 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
1b680 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
1b690 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
1b6a0 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
1b6b0 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
1b6c0 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66  iguity..**.** If
1b6d0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1b6e0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
1b6f0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
1b700 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
1b710 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
1b720 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
1b730 20 20 54 68 69 73 20 70 72 69 76 61 74 65 20 64    This private d
1b740 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
1b750 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
1b760 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
1b770 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
1b780 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
1b790 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
1b7a0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1b7b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
1b7c0 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
1b7d0 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
1b7e0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1b7f0 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
1b800 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
1b810 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
1b820 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
1b830 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b840 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49  n should use.  I
1b850 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
1b860 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
1b870 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1b880 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1b890 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1b8a0 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
1b8b0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
1b8c0 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
1b8d0 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
1b8e0 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
1b8f0 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
1b900 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
1b910 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1b920 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55  n_v2() must be U
1b930 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
1b940 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
1b950 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
1b960 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
1b970 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
1b980 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
1b990 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
1b9a0 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
1b9b0 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
1b9c0 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
1b9d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
1b9e0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
1b9f0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  2()..**.** INVAR
1ba00 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
1ba10 32 37 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2701} The [sqlit
1ba20 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
1ba30 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
1ba40 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
1ba50 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1ba60 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 63  ()] interfaces c
1ba70 72 65 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20  reate a new.**  
1ba80 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
1ba90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73  e connection] as
1baa0 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
1bab0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 64 61            the da
1bac0 74 61 62 61 73 65 20 66 69 6c 65 20 67 69 76 65  tabase file give
1bad0 6e 20 69 6e 20 74 68 65 69 72 20 66 69 72 73 74  n in their first
1bae0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1baf0 2a 20 7b 48 31 32 37 30 32 7d 20 54 68 65 20 66  * {H12702} The f
1bb00 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1bb10 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1bb20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20  as UTF-8.**     
1bb30 20 20 20 20 20 66 6f 72 20 5b 73 71 6c 69 74 65       for [sqlite
1bb40 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73  3_open()] and [s
1bb50 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1bb60 5d 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 0a  ] and as UTF-16.
1bb70 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 74  **          in t
1bb80 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
1bb90 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65  rder for [sqlite
1bba0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a  3_open16()]..**.
1bbb0 2a 2a 20 7b 48 31 32 37 30 33 7d 20 41 20 73 75  ** {H12703} A su
1bbc0 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
1bbd0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1bbe0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
1bbf0 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20  3_open16()],.** 
1bc00 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
1bc10 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
1bc20 77 72 69 74 65 73 20 61 20 70 6f 69 6e 74 65 72  writes a pointer
1bc30 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20   to a new.**    
1bc40 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
1bc50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 6f  connection] into
1bc60 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 48   *ppDb..**.** {H
1bc70 31 32 37 30 34 7d 20 54 68 65 20 5b 73 71 6c 69  12704} The [sqli
1bc80 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1bc90 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
1bca0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
1bcb0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1bcc0 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
1bcd0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1bce0 4b 5d 20 75 70 6f 6e 20 73 75 63 63 65 73 73 2c  K] upon success,
1bcf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
1bd00 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b  an appropriate [
1bd10 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66  error code] on f
1bd20 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ailure..**.** {H
1bd30 31 32 37 30 36 7d 20 54 68 65 20 64 65 66 61 75  12706} The defau
1bd40 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  lt text encoding
1bd50 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62   for a new datab
1bd60 61 73 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  ase created usin
1bd70 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
1bd80 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f  qlite3_open()] o
1bd90 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
1bda0 76 32 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54  v2()] will be UT
1bdb0 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  F-8..**.** {H127
1bdc0 30 37 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20  07} The default 
1bdd0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  text encoding fo
1bde0 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65  r a new database
1bdf0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
1be00 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1be10 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 77 69  te3_open16()] wi
1be20 6c 6c 20 62 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  ll be UTF-16..**
1be30 0a 2a 2a 20 7b 48 31 32 37 30 39 7d 20 54 68 65  .** {H12709} The
1be40 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 46   [sqlite3_open(F
1be50 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69  ,D)] interface i
1be60 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a  s equivalent to.
1be70 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1be80 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
1be90 2c 47 2c 30 29 5d 20 77 68 65 72 65 20 74 68 65  ,G,0)] where the
1bea0 20 47 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a   G parameter is.
1beb0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
1bec0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1bed0 54 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  TE]|[SQLITE_OPEN
1bee0 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20  _CREATE]..**.** 
1bef0 7b 48 31 32 37 31 31 7d 20 49 66 20 74 68 65 20  {H12711} If the 
1bf00 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  G parameter to [
1bf10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1bf20 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69  F,D,G,V)] contai
1bf30 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
1bf40 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51     bit value [SQ
1bf50 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
1bf60 4c 59 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74  LY] then the dat
1bf70 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a  abase is opened.
1bf80 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  **          for 
1bf90 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a  reading only..**
1bfa0 0a 2a 2a 20 7b 48 31 32 37 31 32 7d 20 49 66 20  .** {H12712} If 
1bfb0 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20  the G parameter 
1bfc0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
1bfd0 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f  _v2(F,D,G,V)] co
1bfe0 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20  ntains the.**   
1bff0 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65         bit value
1c000 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
1c010 41 44 57 52 49 54 45 5d 20 74 68 65 6e 20 74 68  ADWRITE] then th
1c020 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1c030 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ened.**         
1c040 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1c050 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
1c060 2c 20 6f 72 20 66 6f 72 20 72 65 61 64 69 6e 67  , or for reading
1c070 20 6f 6e 6c 79 20 69 66 20 74 68 65 0a 2a 2a 20   only if the.** 
1c080 20 20 20 20 20 20 20 20 20 66 69 6c 65 20 69 73           file is
1c090 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
1c0a0 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
1c0b0 67 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  g system..**.** 
1c0c0 7b 48 31 32 37 31 33 7d 20 49 66 20 74 68 65 20  {H12713} If the 
1c0d0 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  G parameter to [
1c0e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32 28  sqlite3_open(v2(
1c0f0 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 20  F,D,G,V)] omits 
1c100 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1c110 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  bit value [SQLIT
1c120 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61  E_OPEN_CREATE] a
1c130 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  nd the database 
1c140 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20  does not.**     
1c150 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20       previously 
1c160 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
1c170 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1c180 2a 2a 20 7b 48 31 32 37 31 34 7d 20 49 66 20 74  ** {H12714} If t
1c190 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74  he G parameter t
1c1a0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
1c1b0 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e  v2(F,D,G,V)] con
1c1c0 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  tains the.**    
1c1d0 20 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20        bit value 
1c1e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
1c1f0 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74  ATE] and the dat
1c200 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
1c210 2a 20 20 20 20 20 20 20 20 20 20 70 72 65 76 69  *          previ
1c220 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 74 68 65  ously exist, the
1c230 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  n an attempt is 
1c240 6d 61 64 65 20 74 6f 20 63 72 65 61 74 65 20 61  made to create a
1c250 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  nd.**          i
1c260 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 64 61  nitialize the da
1c270 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tabase..**.** {H
1c280 31 32 37 31 37 7d 20 49 66 20 74 68 65 20 66 69  12717} If the fi
1c290 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
1c2a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
1c2b0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1c2c0 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  en16()],.**     
1c2d0 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
1c2e0 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 22  _open_v2()] is "
1c2f0 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
1c300 61 6e 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20  an private,.**  
1c310 20 20 20 20 20 20 20 20 65 70 68 65 6d 65 72 61          ephemera
1c320 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  l, in-memory dat
1c330 61 62 61 73 65 20 69 73 20 63 72 65 61 74 65 64  abase is created
1c340 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
1c350 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ion..**         
1c360 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45   <todo>Is SQLITE
1c370 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c  _OPEN_CREATE|SQL
1c380 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1c390 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20  TE required.**  
1c3a0 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74          in sqlit
1c3b0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74  e3_open_v2()?</t
1c3c0 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  odo>.**.** {H127
1c3d0 31 39 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e  19} If the filen
1c3e0 61 6d 65 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61  ame is NULL or a
1c3f0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
1c400 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 0a  then a private,.
1c410 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70 68 65  **          ephe
1c420 6d 65 72 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61  meral on-disk da
1c430 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
1c440 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20  reated..**      
1c450 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c      <todo>Is SQL
1c460 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c  ITE_OPEN_CREATE|
1c470 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1c480 57 52 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a  WRITE required.*
1c490 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 73 71  *          in sq
1c4a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f  lite3_open_v2()?
1c4b0 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48  </todo>.**.** {H
1c4c0 31 32 37 32 31 7d 20 54 68 65 20 5b 64 61 74 61  12721} The [data
1c4d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1c4e0 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c   created by [sql
1c4f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
1c500 2c 47 2c 56 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,G,V)].**       
1c510 20 20 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20     will use the 
1c520 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1c530 6a 65 63 74 20 69 64 65 6e 74 69 66 69 65 64 20  ject identified 
1c540 62 79 20 74 68 65 20 56 20 70 61 72 61 6d 65 74  by the V paramet
1c550 65 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  er,.**          
1c560 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  or the default [
1c570 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1c580 65 63 74 20 69 66 20 56 20 69 73 20 61 20 4e 55  ect if V is a NU
1c590 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1c5a0 2a 20 7b 48 31 32 37 32 33 7d 20 54 77 6f 20 5b  * {H12723} Two [
1c5b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c5c0 69 6f 6e 73 5d 20 77 69 6c 6c 20 73 68 61 72 65  ions] will share
1c5d0 20 61 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 20   a common cache 
1c5e0 69 66 20 62 6f 74 68 20 77 65 72 65 0a 2a 2a 20  if both were.** 
1c5f0 20 20 20 20 20 20 20 20 20 6f 70 65 6e 65 64 20           opened 
1c600 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 56 46  with the same VF
1c610 53 20 77 68 69 6c 65 20 5b 73 68 61 72 65 64 20  S while [shared 
1c620 63 61 63 68 65 20 6d 6f 64 65 5d 20 77 61 73 20  cache mode] was 
1c630 65 6e 61 62 6c 65 64 20 61 6e 64 0a 2a 2a 20 20  enabled and.**  
1c640 20 20 20 20 20 20 20 20 69 66 20 62 6f 74 68 20          if both 
1c650 66 69 6c 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72  filenames compar
1c660 65 20 65 71 75 61 6c 20 75 73 69 6e 67 20 6d 65  e equal using me
1c670 6d 63 6d 70 28 29 20 61 66 74 65 72 20 68 61 76  mcmp() after hav
1c680 69 6e 67 20 62 65 65 6e 0a 2a 2a 20 20 20 20 20  ing been.**     
1c690 20 20 20 20 20 70 72 6f 63 65 73 73 65 64 20 62       processed b
1c6a0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
1c6b0 66 73 20 7c 20 78 46 75 6c 6c 50 61 74 68 6e 61  fs | xFullPathna
1c6c0 6d 65 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  me] method of th
1c6d0 65 20 56 46 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71  e VFS..*/.int sq
1c6e0 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f  lite3_open(.  co
1c6f0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
1c700 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
1c710 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
1c720 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
1c730 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
1c740 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1c750 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
1c760 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
1c770 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
1c780 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
1c790 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
1c7a0 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
1c7b0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
1c7c0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1c7d0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1c7e0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1c7f0 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
1c800 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
1c810 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
1c820 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
1c830 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
1c840 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
1c850 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1c860 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
1c870 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
1c880 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
1c890 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1c8a0 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
1c8b0 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
1c8c0 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
1c8d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c8e0 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20  Error Codes And 
1c8f0 4d 65 73 73 61 67 65 73 20 7b 48 31 32 38 30 30  Messages {H12800
1c900 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60200>.**.**
1c910 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72   The sqlite3_err
1c920 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65  code() interface
1c930 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1c940 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
1c950 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
1c960 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
1c970 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63  for the most rec
1c980 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74  ent failed sqlit
1c990 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a  e3_* API call.**
1c9a0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1c9b0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
1c9c0 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70  nection]. If a p
1c9d0 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61  rior API call fa
1c9e0 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20  iled.** but the 
1c9f0 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
1ca00 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20  call succeeded, 
1ca10 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1ca20 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33   from.** sqlite3
1ca30 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e  _errcode() is un
1ca40 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
1ca50 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
1ca60 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
1ca70 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
1ca80 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
1ca90 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
1caa0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
1cab0 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
1cac0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
1cad0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
1cae0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
1caf0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
1cb00 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
1cb10 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
1cb20 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1cb30 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
1cb40 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
1cb50 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
1cb60 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
1cb70 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
1cb80 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
1cb90 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
1cba0 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
1cbb0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
1cbc0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
1cbd0 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  face functions..
1cbe0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
1cbf0 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
1cc00 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
1cc10 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
1cc20 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
1cc30 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
1cc40 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
1cc50 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
1cc60 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
1cc70 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
1cc80 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
1cc90 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  not be set..**.*
1cca0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1ccb0 0a 2a 2a 20 7b 48 31 32 38 30 31 7d 20 54 68 65  .** {H12801} The
1ccc0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1ccd0 65 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(D)] interface 
1cce0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
1ccf0 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ric.**          
1cd00 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
1cd10 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
1cd20 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
1cd30 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a 2a 2a  most recently.**
1cd40 20 20 20 20 20 20 20 20 20 20 66 61 69 6c 65 64            failed
1cd50 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20   interface call 
1cd60 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1cd70 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
1cd80 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
1cd90 2a 2a 20 7b 48 31 32 38 30 33 7d 20 54 68 65 20  ** {H12803} The 
1cda0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1cdb0 44 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  D)] and [sqlite3
1cdc0 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 0a 2a 2a  _errmsg16(D)].**
1cdd0 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
1cde0 61 63 65 73 20 72 65 74 75 72 6e 20 45 6e 67 6c  aces return Engl
1cdf0 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78  ish-language tex
1ce00 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
1ce10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1ce20 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20 6d 6f   error in the mo
1ce30 73 74 6c 79 20 72 65 63 65 6e 74 6c 79 20 66 61  stly recently fa
1ce40 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65 20 63  iled interface c
1ce50 61 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  all,.**         
1ce60 20 65 6e 63 6f 64 65 64 20 61 73 20 65 69 74 68   encoded as eith
1ce70 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1ce80 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
1ce90 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 37 7d 20  .**.** {H12807} 
1cea0 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
1ceb0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1cec0 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b  _errmsg()] and [
1ced0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1cee0 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
1cef0 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
1cf00 74 68 65 20 6e 65 78 74 20 53 51 4c 69 74 65 20  the next SQLite 
1cf10 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a  interface call..
1cf20 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 38 7d 20 43  **.** {H12808} C
1cf30 61 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f 75 74  alls to API rout
1cf40 69 6e 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  ines that do not
1cf50 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72   return an error
1cf60 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
1cf70 20 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c    (example: [sql
1cf80 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
1cf90 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20  )]) do not.**   
1cfa0 20 20 20 20 20 20 20 63 68 61 6e 67 65 20 74 68         change th
1cfb0 65 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 72 20  e error code or 
1cfc0 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e 65 64  message returned
1cfd0 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
1cfe0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
1cff0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72  ()], [sqlite3_er
1d000 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c  rmsg()], or [sql
1d010 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
1d020 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 39 7d  ..**.** {H12809}
1d030 20 49 6e 74 65 72 66 61 63 65 73 20 74 68 61 74   Interfaces that
1d040 20 61 72 65 20 6e 6f 74 20 61 73 73 6f 63 69 61   are not associa
1d050 74 65 64 20 77 69 74 68 20 61 20 73 70 65 63 69  ted with a speci
1d060 66 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  fic.**          
1d070 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1d080 74 69 6f 6e 5d 20 28 65 78 61 6d 70 6c 65 73 3a  tion] (examples:
1d090 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1d0a0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
1d0b0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61   or [sqlite3_ena
1d0c0 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
1d0d0 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
1d0e0 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  do not change th
1d0f0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
1d100 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
1d110 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1d120 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65  e()], [sqlite3_e
1d130 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71  rrmsg()], or [sq
1d140 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1d150 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
1d160 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
1d170 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68  3 *db);.const ch
1d180 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
1d190 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  sg(sqlite3*);.co
1d1a0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
1d1b0 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
1d1c0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1d1d0 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65  I3REF: SQL State
1d1e0 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33  ment Object {H13
1d1f0 30 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 2a  000} <H13010>.**
1d200 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
1d210 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
1d220 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
1d230 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
1d240 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
1d250 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
1d260 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  s a single SQL s
1d270 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69  tatement..** Thi
1d280 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69  s object is vari
1d290 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61  ously known as a
1d2a0 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65   "prepared state
1d2b0 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63  ment" or a.** "c
1d2c0 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
1d2d0 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79  ement" or simply
1d2e0 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74   as a "statement
1d2f0 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66  "..**.** The lif
1d300 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74  e of a statement
1d310 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d   object goes som
1d320 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73  ething like this
1d330 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
1d340 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20  <li> Create the 
1d350 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
1d360 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1d370 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64  ()] or a related
1d380 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f  .**      functio
1d390 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20  n..** <li> Bind 
1d3a0 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20  values to [host 
1d3b0 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e  parameters] usin
1d3c0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
1d3d0 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69  nd_*().**      i
1d3e0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c  nterfaces..** <l
1d3f0 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
1d400 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
1d410 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
1d420 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
1d430 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
1d440 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
1d450 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1d460 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
1d470 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
1d480 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
1d490 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
1d4a0 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
1d4b0 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
1d4c0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1d4d0 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
1d4e0 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f  *.** Refer to do
1d4f0 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69  cumentation on i
1d500 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64  ndividual method
1d510 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69  s above for addi
1d520 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
1d530 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ation..*/.typede
1d540 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
1d550 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
1d560 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
1d570 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
1d580 6d 69 74 73 20 7b 48 31 32 37 36 30 7d 20 3c 53  mits {H12760} <S
1d590 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  20600>.**.** Thi
1d5a0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
1d5b0 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76  ws the size of v
1d5c0 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74  arious construct
1d5d0 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a  s to be limited.
1d5e0 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69  ** on a connecti
1d5f0 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e  on by connection
1d600 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72   basis.  The fir
1d610 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
1d620 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
1d630 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f   connection] who
1d640 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62  se limit is to b
1d650 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64  e set or queried
1d660 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
1d670 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
1d680 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20  e of the [limit 
1d690 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74  categories] that
1d6a0 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61   define a.** cla
1d6b0 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73  ss of constructs
1d6c0 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69   to be size limi
1d6d0 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20  ted.  The third 
1d6e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
1d6f0 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f  .** new limit fo
1d700 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74  r that construct
1d710 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20  .  The function 
1d720 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20  returns the old 
1d730 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  limit..**.** If 
1d740 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
1d750 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
1d760 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
1d770 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46   unchanged..** F
1d780 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74  or the limit cat
1d790 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f  egory of SQLITE_
1d7a0 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20  LIMIT_XYZ there 
1d7b0 69 73 20 61 20 68 61 72 64 20 75 70 70 65 72 0a  is a hard upper.
1d7c0 2a 2a 20 62 6f 75 6e 64 20 73 65 74 20 62 79 20  ** bound set by 
1d7d0 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43  a compile-time C
1d7e0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1d7f0 63 72 6f 20 6e 61 6d 65 64 20 53 51 4c 49 54 45  cro named SQLITE
1d800 5f 4d 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54 68  _MAX_XYZ..** (Th
1d810 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
1d820 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
1d830 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a  ed to "_MAX_".).
1d840 2a 2a 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69  ** Attempts to i
1d850 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
1d860 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
1d870 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
1d880 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
1d890 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
1d8a0 20 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a   upper limit..**
1d8b0 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d  .** Run time lim
1d8c0 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  its are intended
1d8d0 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c   for use in appl
1d8e0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61  ications that ma
1d8f0 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65  nage.** both the
1d900 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20  ir own internal 
1d910 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73  database and als
1d920 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74  o databases that
1d930 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a   are controlled.
1d940 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20  ** by untrusted 
1d950 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
1d960 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70  .  An example ap
1d970 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
1d980 62 65 20 61 0a 2a 2a 20 77 65 62 62 72 6f 77 73  be a.** webbrows
1d990 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20  er that has its 
1d9a0 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f  own databases fo
1d9b0 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72  r storing histor
1d9c0 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74  y and.** separat
1d9d0 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74  e databases cont
1d9e0 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63  rolled by JavaSc
1d9f0 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ript application
1da00 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20  s downloaded.** 
1da10 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74  off the Internet
1da20 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20  .  The internal 
1da30 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65  databases can be
1da40 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61   given the.** la
1da50 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d  rge, default lim
1da60 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20  its.  Databases 
1da70 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72  managed by exter
1da80 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a  nal sources can.
1da90 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68  ** be given much
1daa0 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20   smaller limits 
1dab0 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76  designed to prev
1dac0 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20  ent a denial of 
1dad0 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63  service.** attac
1dae0 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d  k.  Developers m
1daf0 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74  ight also want t
1db00 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74  o use the [sqlit
1db10 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1db20 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  r()].** interfac
1db30 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e  e to further con
1db40 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53  trol untrusted S
1db50 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  QL.  The size of
1db60 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
1db70 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75   created by an u
1db80 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20  ntrusted script 
1db90 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  can be contained
1dba0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d   using the.** [m
1dbb0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
1dbc0 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e  PRAGMA]..**.** N
1dbd0 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69  ew run-time limi
1dbe0 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79  t categories may
1dbf0 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
1dc00 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  ure releases..**
1dc10 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1dc20 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 32 7d 20 41  **.** {H12762} A
1dc30 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
1dc40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   to [sqlite3_lim
1dc50 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65  it(D,C,V)] where
1dc60 20 56 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20   V is.**        
1dc70 20 20 70 6f 73 69 74 69 76 65 20 63 68 61 6e 67    positive chang
1dc80 65 73 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20  es the limit on 
1dc90 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73  the size of cons
1dca0 74 72 75 63 74 20 43 20 69 6e 20 74 68 65 0a 2a  truct C in the.*
1dcb0 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
1dcc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1dcd0 20 44 20 74 6f 20 74 68 65 20 6c 65 73 73 65 72   D to the lesser
1dce0 20 6f 66 20 56 20 61 6e 64 20 74 68 65 20 68 61   of V and the ha
1dcf0 72 64 20 75 70 70 65 72 0a 2a 2a 20 20 20 20 20  rd upper.**     
1dd00 20 20 20 20 20 62 6f 75 6e 64 20 6f 6e 20 74 68       bound on th
1dd10 65 20 73 69 7a 65 20 6f 66 20 43 20 74 68 61 74  e size of C that
1dd20 20 69 73 20 73 65 74 20 61 74 20 63 6f 6d 70 69   is set at compi
1dd30 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b  le-time..**.** {
1dd40 48 31 32 37 36 36 7d 20 41 20 73 75 63 63 65 73  H12766} A succes
1dd50 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
1dd60 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c  lite3_limit(D,C,
1dd70 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 20 6e  V)] where V is n
1dd80 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20  egative.**      
1dd90 20 20 20 20 6c 65 61 76 65 73 20 74 68 65 20 73      leaves the s
1dda0 74 61 74 65 20 6f 66 20 74 68 65 20 5b 64 61 74  tate of the [dat
1ddb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ddc0 5d 20 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ] D unchanged..*
1ddd0 2a 0a 2a 2a 20 7b 48 31 32 37 36 39 7d 20 41 20  *.** {H12769} A 
1dde0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
1ddf0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  to [sqlite3_limi
1de00 74 28 44 2c 43 2c 56 29 5d 20 72 65 74 75 72 6e  t(D,C,V)] return
1de10 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
1de20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c    value of the l
1de30 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65  imit on the size
1de40 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20   of construct C 
1de50 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
1de60 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
1de70 6e 65 63 74 69 6f 6e 5d 20 44 20 61 73 20 69 74  nection] D as it
1de80 20 77 61 73 20 70 72 69 6f 72 20 74 6f 20 74 68   was prior to th
1de90 65 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  e call..*/.int s
1dea0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
1deb0 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
1dec0 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
1ded0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1dee0 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
1def0 67 6f 72 69 65 73 20 7b 48 31 32 37 39 30 7d 20  gories {H12790} 
1df00 3c 48 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 57  <H12760>.** KEYW
1df10 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
1df20 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61  egory} {limit ca
1df30 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
1df40 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
1df50 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 61  define various a
1df60 73 70 65 63 74 73 20 6f 66 20 61 20 5b 64 61 74  spects of a [dat
1df70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1df80 5d 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  ].** that can be
1df90 20 6c 69 6d 69 74 65 64 20 69 6e 20 73 69 7a 65   limited in size
1dfa0 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   by calls to [sq
1dfb0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a  lite3_limit()]..
1dfc0 2a 2a 20 54 68 65 20 6d 65 61 6e 69 6e 67 73 20  ** The meanings 
1dfd0 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  of the various l
1dfe0 69 6d 69 74 73 20 61 72 65 20 61 73 20 66 6f 6c  imits are as fol
1dff0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  lows:.**.** <dl>
1e000 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1e010 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  IMIT_LENGTH</dt>
1e020 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1e030 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20  mum size of any 
1e040 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f  string or BLOB o
1e050 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e  r table row.<dd>
1e060 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1e070 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
1e080 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1e090 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
1e0a0 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
1e0b0 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ement.</dd>.**.*
1e0c0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1e0d0 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
1e0e0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1e0f0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
1e100 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
1e110 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
1e120 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
1e130 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 6f 72  t of a SELECT or
1e140 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
1e150 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1e160 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
1e170 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
1e180 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
1e190 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  se.</dd>.**.** <
1e1a0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1e1b0 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
1e1c0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1e1d0 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
1e1e0 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
1e1f0 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
1e200 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1e210 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
1e220 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
1e230 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1e240 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
1e250 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
1e260 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
1e270 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1e280 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  >SQLITE_LIMIT_VD
1e290 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BE_OP</dt>.** <d
1e2a0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1e2b0 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74  mber of instruct
1e2c0 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61  ions in a virtua
1e2d0 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61  l machine progra
1e2e0 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70  m.** used to imp
1e2f0 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74  lement an SQL st
1e300 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a  atement.</dd>.**
1e310 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1e320 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
1e330 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
1e340 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1e350 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
1e360 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
1e370 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1e380 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
1e390 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
1e3a0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1e3b0 20 6f 66 20 61 74 74 61 63 68 65 64 20 64 61 74   of attached dat
1e3c0 61 62 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  abases.</dd>.**.
1e3d0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1e3e0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
1e3f0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1e400 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1e410 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
1e420 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
1e430 6f 20 74 68 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a  o the LIKE or.**
1e440 20 47 4c 4f 42 20 6f 70 65 72 61 74 6f 72 73 2e   GLOB operators.
1e450 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1e460 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
1e470 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
1e480 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1e490 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76  imum number of v
1e4a0 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53  ariables in an S
1e4b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
1e4c0 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e  t can.** be boun
1e4d0 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e  d.</dd>.** </dl>
1e4e0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1e4f0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
1e500 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e510 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
1e520 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
1e530 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
1e540 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
1e550 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
1e560 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
1e570 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
1e580 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
1e590 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
1e5a0 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
1e5b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
1e5c0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
1e5d0 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
1e5e0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
1e5f0 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
1e600 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
1e610 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
1e620 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
1e630 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
1e640 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1e650 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
1e660 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
1e670 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1e680 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
1e690 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
1e6a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1e6b0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1e6c0 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f  R           9../
1e6d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1e6e0 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
1e6f0 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 31  Statement {H1301
1e700 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b  0} <S10000>.** K
1e710 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
1e720 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
1e730 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
1e740 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
1e750 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
1e760 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
1e770 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
1e780 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
1e790 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1e7a0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
1e7b0 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
1e7c0 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
1e7d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
1e7e0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
1e7f0 2a 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  * prior call to 
1e800 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1e810 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
1e820 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
1e830 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a  3_open16()]..**.
1e840 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
1e850 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
1e860 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
1e870 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
1e880 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
1e890 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
1e8a0 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
1e8b0 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
1e8c0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
1e8d0 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
1e8e0 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
1e8f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1e900 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
1e910 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1e920 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
1e930 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e  ..**.** If the n
1e940 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
1e950 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
1e960 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
1e970 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
1e980 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
1e990 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 20  nator. If nByte 
1e9a0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
1e9b0 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20   then it is the 
1e9c0 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65  maximum.** numbe
1e9d0 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64  r of  bytes read
1e9e0 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65   from zSql.  Whe
1e9f0 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  n nByte is non-n
1ea00 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20  egative, the.** 
1ea10 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73  zSql string ends
1ea20 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66   at either the f
1ea30 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27  irst '\000' or '
1ea40 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65  \u0000' characte
1ea50 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74  r or.** the nByt
1ea60 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68  e-th byte, which
1ea70 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
1ea80 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20  . If the caller 
1ea90 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68  knows.** that th
1eaa0 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
1eab0 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
1eac0 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20  ted, then there 
1ead0 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65  is a small.** pe
1eae0 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
1eaf0 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64  age to be gained
1eb00 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e   by passing an n
1eb10 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74  Byte parameter t
1eb20 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20  hat.** is equal 
1eb30 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  to the number of
1eb40 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e   bytes in the in
1eb50 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e  put string <i>in
1eb60 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74  cluding</i>.** t
1eb70 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f  he nul-terminato
1eb80 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a  r bytes..**.** *
1eb90 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
1eba0 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
1ebb0 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20 74  irst byte past t
1ebc0 68 65 20 65 6e 64 20 6f 66 20 74 68 65 0a 2a 2a  he end of the.**
1ebd0 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
1ebe0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
1ebf0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
1ec00 6c 79 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66  ly compile the f
1ec10 69 72 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  irst.** statemen
1ec20 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
1ec30 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
1ec40 69 6e 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72  inting to what r
1ec50 65 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70  emains.** uncomp
1ec60 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53  iled..**.** *ppS
1ec70 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
1ec80 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
1ec90 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
1eca0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
1ecb0 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
1ecc0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
1ecd0 74 65 70 28 29 5d 2e 20 20 49 66 20 74 68 65 72  tep()].  If ther
1ece0 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
1ecf0 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a  ppStmt is set.**
1ed00 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68   to NULL.  If th
1ed10 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  e input text con
1ed20 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66  tains no SQL (if
1ed30 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e   the input is an
1ed40 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67   empty.** string
1ed50 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74   or a comment) t
1ed60 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73  hen *ppStmt is s
1ed70 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b  et to NULL..** {
1ed80 41 31 33 30 31 38 7d 20 54 68 65 20 63 61 6c 6c  A13018} The call
1ed90 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
1eda0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
1edb0 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
1edc0 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74  mpiled.** SQL st
1edd0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
1ede0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1edf0 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
1ee00 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
1ee10 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65  ..**.** On succe
1ee20 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  ss, [SQLITE_OK] 
1ee30 69 73 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 68  is returned, oth
1ee40 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
1ee50 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
1ee60 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1ee70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1ee80 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
1ee90 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
1eea0 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
1eeb0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
1eec0 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
1eed0 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
1eee0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
1eef0 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
1ef00 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1ef10 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
1ef20 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
1ef30 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20  aged..** In the 
1ef40 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c  "v2" interfaces,
1ef50 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
1ef60 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20  atement.** that 
1ef70 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65  is returned (the
1ef80 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
1ef90 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73  object) contains
1efa0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
1efb0 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
1efc0 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73  ext. This causes
1efd0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
1efe0 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ep()] interface 
1eff0 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64  to.** behave a d
1f000 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77  ifferently in tw
1f010 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  o ways:.**.** <o
1f020 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66  l>.** <li>.** If
1f030 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
1f040 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
1f050 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
1f060 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
1f070 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
1f080 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
1f090 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f0a0 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
1f0b0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
1f0c0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
1f0d0 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
1f0e0 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74   it again.  If t
1f0f0 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68  he schema has ch
1f100 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61  anged in.** a wa
1f110 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  y that makes the
1f120 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f   statement no lo
1f130 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c  nger valid, [sql
1f140 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
1f150 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  l still.** retur
1f160 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
1f170 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74  ].  But unlike t
1f180 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
1f190 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  or, [SQLITE_SCHE
1f1a0 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20  MA] is.** now a 
1f1b0 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61  fatal error.  Ca
1f1c0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  lling [sqlite3_p
1f1d0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61  repare_v2()] aga
1f1e0 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65  in will not make
1f1f0 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f   the.** error go
1f200 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73   away.  Note: us
1f210 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  e [sqlite3_errms
1f220 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65  g()] to find the
1f230 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20   text.** of the 
1f240 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68  parsing error th
1f250 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e  at results in an
1f260 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1f270 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69   return..** </li
1f280 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
1f290 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
1f2a0 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73  curs, [sqlite3_s
1f2b0 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
1f2c0 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
1f2d0 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72  tailed.** [error
1f2e0 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
1f2f0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
1f300 5d 2e 20 20 54 68 65 20 6c 65 67 61 63 79 20 62  ].  The legacy b
1f310 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
1f320 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
1f330 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
1f340 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
1f350 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
1f360 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
1f370 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76  nd you would hav
1f380 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
1f390 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
1f3a0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20  te3_reset()] in 
1f3b0 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64  order.** to find
1f3c0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
1f3d0 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
1f3e0 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
1f3f0 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
1f400 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
1f410 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
1f420 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
1f430 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
1f440 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
1f450 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
1f460 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1f470 2a 20 7b 48 31 33 30 31 31 7d 20 54 68 65 20 5b  * {H13011} The [
1f480 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1f490 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e  db,zSql,...)] an
1f4a0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
1f4b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1f4c0 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20  2(db,zSql,...)] 
1f4d0 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65 72  interfaces inter
1f4e0 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  pret the.**     
1f4f0 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 68 65       text in the
1f500 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65  ir zSql paramete
1f510 72 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  r as UTF-8..**.*
1f520 2a 20 7b 48 31 33 30 31 32 7d 20 54 68 65 20 5b  * {H13012} The [
1f530 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1f540 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20  6(db,zSql,...)] 
1f550 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
1f560 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f570 31 36 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e  16_v2(db,zSql,..
1f580 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69  .)] interfaces i
1f590 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20  nterpret the.** 
1f5a0 20 20 20 20 20 20 20 20 20 74 65 78 74 20 69 6e           text in
1f5b0 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61   their zSql para
1f5c0 6d 65 74 65 72 20 61 73 20 55 54 46 2d 31 36 20  meter as UTF-16 
1f5d0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1f5e0 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20  te order..**.** 
1f5f0 7b 48 31 33 30 31 33 7d 20 49 66 20 74 68 65 20  {H13013} If the 
1f600 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74  nByte argument t
1f610 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
1f620 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42  re_v2(db,zSql,nB
1f630 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  yte,...)].**    
1f640 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 61        and its va
1f650 72 69 61 6e 74 73 20 69 73 20 6c 65 73 73 20 74  riants is less t
1f660 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 20 53 51  han zero, the SQ
1f670 4c 20 74 65 78 74 20 69 73 0a 2a 2a 20 20 20 20  L text is.**    
1f680 20 20 20 20 20 20 72 65 61 64 20 66 72 6f 6d 20        read from 
1f690 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
1f6a0 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
1f6b0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
1f6c0 0a 2a 2a 20 7b 48 31 33 30 31 34 7d 20 49 66 20  .** {H13014} If 
1f6d0 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
1f6e0 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  nt to [sqlite3_p
1f6f0 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71  repare_v2(db,zSq
1f700 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a  l,nByte,...)].**
1f710 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 69 74            and it
1f720 73 20 76 61 72 69 61 6e 74 73 20 69 73 20 6e 6f  s variants is no
1f730 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
1f740 20 61 74 20 6d 6f 73 74 20 6e 42 79 74 65 73 20   at most nBytes 
1f750 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20  bytes of.**     
1f760 20 20 20 20 20 53 51 4c 20 74 65 78 74 20 69 73       SQL text is
1f770 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
1f780 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 35 7d 20  .**.** {H13015} 
1f790 49 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  In [sqlite3_prep
1f7a0 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e  are_v2(db,zSql,N
1f7b0 2c 50 2c 70 7a 54 61 69 6c 29 5d 20 61 6e 64 20  ,P,pzTail)] and 
1f7c0 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20  its variants.** 
1f7d0 20 20 20 20 20 20 20 20 20 69 66 20 74 68 65 20           if the 
1f7e0 7a 53 71 6c 20 69 6e 70 75 74 20 74 65 78 74 20  zSql input text 
1f7f0 63 6f 6e 74 61 69 6e 73 20 6d 6f 72 65 20 74 68  contains more th
1f800 61 6e 20 6f 6e 65 20 53 51 4c 20 73 74 61 74 65  an one SQL state
1f810 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  ment.**         
1f820 20 61 6e 64 20 70 7a 54 61 69 6c 20 69 73 20 6e   and pzTail is n
1f830 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a 70  ot NULL, then *p
1f840 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
1f850 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 0a 2a 2a   point to the.**
1f860 20 20 20 20 20 20 20 20 20 20 66 69 72 73 74 20            first 
1f870 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65 6e  byte past the en
1f880 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
1f890 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1f8a0 7a 53 71 6c 2e 0a 2a 2a 20 20 20 20 20 20 20 20  zSql..**        
1f8b0 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 64 6f 65    <todo>What doe
1f8c0 73 20 2a 70 7a 54 61 69 6c 20 70 6f 69 6e 74 20  s *pzTail point 
1f8d0 74 6f 20 69 66 20 74 68 65 72 65 20 69 73 20 6f  to if there is o
1f8e0 6e 65 20 73 74 61 74 65 6d 65 6e 74 3f 3c 2f 74  ne statement?</t
1f8f0 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30  odo>.**.** {H130
1f900 31 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  16} A successful
1f910 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1f920 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c  3_prepare_v2(db,
1f930 7a 53 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e  zSql,N,ppStmt,..
1f940 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
1f950 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
1f960 72 69 61 6e 74 73 20 77 72 69 74 65 73 20 69 6e  riants writes in
1f970 74 6f 20 2a 70 70 53 74 6d 74 20 61 20 70 6f 69  to *ppStmt a poi
1f980 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a  nter to a new.**
1f990 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
1f9a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
1f9b0 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e  r a pointer to N
1f9c0 55 4c 4c 20 69 66 20 7a 53 71 6c 20 63 6f 6e 74  ULL if zSql cont
1f9d0 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ains.**         
1f9e0 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74   nothing other t
1f9f0 68 61 6e 20 77 68 69 74 65 73 70 61 63 65 20 6f  han whitespace o
1fa00 72 20 63 6f 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  r comments..**.*
1fa10 2a 20 7b 48 31 33 30 31 39 7d 20 54 68 65 20 5b  * {H13019} The [
1fa20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1fa30 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
1fa40 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
1fa50 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20   return.**      
1fa60 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20      [SQLITE_OK] 
1fa70 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  or an appropriat
1fa80 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  e [error code] u
1fa90 70 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a  pon failure..**.
1faa0 2a 2a 20 7b 48 31 33 30 32 31 7d 20 42 65 66 6f  ** {H13021} Befo
1fab0 72 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  re [sqlite3_prep
1fac0 61 72 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74  are(db,zSql,nByt
1fad0 65 2c 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c 29  e,ppStmt,pzTail)
1fae0 5d 20 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20 20  ] or its.**     
1faf0 20 20 20 20 20 76 61 72 69 61 6e 74 73 20 72 65       variants re
1fb00 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 20 28  turns an error (
1fb10 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
1fb20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
1fb30 29 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ),.**          t
1fb40 68 65 79 20 66 69 72 73 74 20 73 65 74 20 2a 70  hey first set *p
1fb50 70 53 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  pStmt to NULL..*
1fb60 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  /.int sqlite3_pr
1fb70 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33  epare(.  sqlite3
1fb80 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1fb90 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1fba0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1fbb0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
1fbc0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1fbd0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
1fbe0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
1fbf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1fc00 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
1fc10 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
1fc20 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
1fc30 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
1fc40 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
1fc50 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1fc60 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
1fc70 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
1fc80 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
1fc90 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
1fca0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1fcb0 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
1fcc0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1fcd0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1fce0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1fcf0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1fd00 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1fd10 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
1fd20 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1fd30 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1fd40 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1fd50 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1fd60 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1fd70 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1fd80 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1fd90 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1fda0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
1fdb0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1fdc0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1fdd0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1fde0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
1fdf0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1fe00 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1fe10 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
1fe20 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
1fe30 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1fe40 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
1fe50 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
1fe60 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
1fe70 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1fe80 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1fe90 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1fea0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1feb0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1fec0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1fed0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1fee0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1fef0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
1ff00 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1ff10 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1ff20 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1ff30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1ff40 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c  pare16_v2(.  sql
1ff50 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1ff60 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
1ff70 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1ff80 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
1ff90 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
1ffa0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
1ffb0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1ffc0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1ffd0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1ffe0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1fff0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
20000 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
20010 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
20020 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
20030 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
20040 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
20050 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
20060 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
20070 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  Sql */.);../*.**
20080 20 43 41 50 49 52 45 46 3a 20 52 65 74 72 69 65   CAPIREF: Retrie
20090 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53  ving Statement S
200a0 51 4c 20 7b 48 31 33 31 30 30 7d 20 3c 48 31 33  QL {H13100} <H13
200b0 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  000>.**.** This 
200c0 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
200d0 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
200e0 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
200f0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
20100 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
20110 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
20120 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
20130 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65   if that stateme
20140 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c  nt was.** compil
20150 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
20160 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20170 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
20180 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
20190 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
201a0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
201b0 31 30 31 7d 20 49 66 20 74 68 65 20 5b 70 72 65  101} If the [pre
201c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
201d0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 61   passed as the a
201e0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20  rgument to.**   
201f0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
20200 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69  sql()] was compi
20210 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
20220 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20230 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20  e_v2()] or.**   
20240 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
20250 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c  prepare16_v2()],
20260 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73   then [sqlite3_s
20270 71 6c 28 29 5d 20 72 65 74 75 72 6e 73 0a 2a 2a  ql()] returns.**
20280 20 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e            a poin
20290 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
202a0 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20  rminated string 
202b0 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20 55 54 46  containing a UTF
202c0 2d 38 20 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20  -8 rendering.** 
202d0 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
202e0 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 73 74 61  original SQL sta
202f0 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tement..**.** {H
20300 31 33 31 30 32 7d 20 49 66 20 74 68 65 20 5b 70  13102} If the [p
20310 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20320 74 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65  t] passed as the
20330 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
20340 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
20350 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d  3_sql()] was com
20360 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
20370 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
20380 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  are()] or.**    
20390 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
203a0 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65  repare16()], the
203b0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  n [sqlite3_sql()
203c0 5d 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ] returns a NULL
203d0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
203e0 7b 48 31 33 31 30 33 7d 20 54 68 65 20 73 74 72  {H13103} The str
203f0 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20  ing returned by 
20400 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 53 29 5d  [sqlite3_sql(S)]
20410 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
20420 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
20430 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
20440 65 6e 74 5d 20 53 20 69 73 20 64 65 6c 65 74 65  ent] S is delete
20450 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
20460 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a  _finalize(S)]..*
20470 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
20480 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
20490 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
204a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
204b0 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
204c0 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 20  ed Value Object 
204d0 7b 48 31 35 30 30 30 7d 20 3c 53 32 30 32 30 30  {H15000} <S20200
204e0 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
204f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
20500 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
20510 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
20520 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
20530 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
20540 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
20550 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
20560 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
20570 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
20580 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
20590 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
205a0 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
205b0 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
205c0 69 74 20 73 74 6f 72 65 73 2e 20 56 61 6c 75 65  it stores. Value
205d0 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
205e0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
205f0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
20600 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
20610 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
20620 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
20630 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
20640 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
20650 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
20660 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
20670 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
20680 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
20690 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
206a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
206b0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
206c0 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
206d0 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
206e0 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
206f0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
20700 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
20710 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
20720 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
20730 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
20740 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
20750 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
20760 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
20770 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
20780 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
20790 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
207a0 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
207b0 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
207c0 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
207d0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
207e0 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65   A internal mute
207f0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
20800 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
20810 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
20820 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
20830 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
20840 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
20850 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
20860 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
20870 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
20880 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
20890 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
208a0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
208b0 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
208c0 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
208d0 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
208e0 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
208f0 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
20900 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
20910 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
20920 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
20930 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
20940 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
20950 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
20960 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
20970 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
20980 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
20990 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
209a0 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
209b0 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
209c0 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
209d0 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
209e0 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
209f0 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
20a00 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
20a10 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
20a20 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
20a30 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
20a40 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72  tween between pr
20a50 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
20a60 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
20a70 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
20a80 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
20a90 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
20aa0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
20ab0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
20ac0 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
20ad0 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
20ae0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
20af0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
20b00 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
20b10 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
20b20 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
20b30 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
20b40 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
20b50 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
20b60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
20b70 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
20b80 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
20b90 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
20ba0 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
20bb0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
20bc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
20bd0 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
20be0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
20bf0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
20c00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
20c10 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
20c20 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
20c30 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
20c40 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
20c50 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
20c60 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
20c70 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
20c80 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
20c90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20ca0 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
20cb0 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20 7b 48  ontext Object {H
20cc0 31 36 30 30 31 7d 20 3c 53 32 30 32 30 30 3e 0a  16001} <S20200>.
20cd0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
20ce0 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
20cf0 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
20d00 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
20d10 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
20d20 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
20d30 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
20d40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
20d50 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77  object.** is alw
20d60 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  ays first parame
20d70 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74  ter to [applicat
20d80 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
20d90 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  functions]..** T
20da0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
20db0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
20dc0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
20dd0 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69  on will pass thi
20de0 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72  s.** pointer thr
20df0 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20  ough into calls 
20e00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
20e10 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  lt_int | sqlite3
20e20 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b  _result()],.** [
20e30 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
20e40 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73  e_context()], [s
20e50 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
20e60 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
20e70 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
20e80 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  le()], [sqlite3_
20e90 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a  get_auxdata()],.
20ea0 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74  ** and/or [sqlit
20eb0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
20ec0 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
20ed0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
20ee0 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
20ef0 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
20f00 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56  I3REF: Binding V
20f10 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65  alues To Prepare
20f20 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b 48 31  d Statements {H1
20f30 33 35 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a  3500} <S70300>.*
20f40 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
20f50 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
20f60 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
20f70 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
20f80 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
20f90 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
20fa0 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
20fb0 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
20fc0 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  nding}.**.** In 
20fd0 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20  the SQL strings 
20fe0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
20ff0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
21000 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
21010 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
21020 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
21030 20 61 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20   a parameter in 
21040 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 66 6f 72  one of these for
21050 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ms:.**.** <ul>.*
21060 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
21070 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
21080 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
21090 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
210a0 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
210b0 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   In the paramete
210c0 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62  r forms shown ab
210d0 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e  ove NNN is an in
210e0 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
210f0 2a 20 61 6e 64 20 56 56 56 20 69 73 20 61 6e 20  * and VVV is an 
21100 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 61  alpha-numeric pa
21110 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 20 54 68  rameter name. Th
21120 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
21130 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
21140 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
21150 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
21160 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
21170 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
21180 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
21190 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
211a0 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
211b0 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54  ed here..**.** T
211c0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
211d0 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
211e0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
211f0 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
21200 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
21210 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
21220 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
21230 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
21240 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
21250 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
21260 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
21270 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
21280 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51   index of the SQ
21290 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  L parameter to b
212a0 65 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20 6c 65  e set..** The le
212b0 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
212c0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
212d0 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68  x of 1.  When th
212e0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
212f0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
21300 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
21310 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
21320 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
21330 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
21340 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
21350 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
21360 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 20 69  rrence..** The i
21370 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
21380 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
21390 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
213a0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
213b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
213c0 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
213d0 64 65 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e  desired.  The in
213e0 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e  dex.** for "?NNN
213f0 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  " parameters is 
21400 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e  the value of NNN
21410 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c  ..** The NNN val
21420 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
21430 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
21440 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
21450 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
21460 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
21470 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
21480 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
21490 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  .**.** The third
214a0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
214b0 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
214c0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
214d0 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  .**.** In those 
214e0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
214f0 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
21500 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
21510 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
21520 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
21530 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
21540 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
21550 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
21560 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
21570 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
21580 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
21590 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
215a0 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
215b0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  h parameter is n
215c0 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e  egative, the len
215d0 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
215e0 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
215f0 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
21600 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
21610 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
21620 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61 72 67  ** The fifth arg
21630 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
21640 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71  _bind_blob(), sq
21650 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
21660 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  ), and.** sqlite
21670 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
21680 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
21690 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
216a0 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
216b0 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
216c0 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
216d0 65 64 20 77 69 74 68 20 69 74 2e 20 49 66 20 74  ed with it. If t
216e0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
216f0 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
21700 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
21710 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
21720 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
21730 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
21740 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
21750 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
21760 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
21770 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
21780 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  ed..** If the fi
21790 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
217a0 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
217b0 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
217c0 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
217d0 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
217e0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
217f0 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
21800 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
21810 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
21820 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
21830 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
21840 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
21850 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
21860 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
21870 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
21880 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
21890 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20  es.  A zeroblob 
218a0 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
218b0 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
218c0 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
218d0 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
218e0 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
218f0 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
21900 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
21910 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
21920 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
21930 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
21940 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
21950 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
21960 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
21970 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
21980 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
21990 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
219a0 20 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75   A negative valu
219b0 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c  e for the zerobl
219c0 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20  ob results in a 
219d0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
219e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
219f0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
21a00 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
21a10 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73  lled after.** [s
21a20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21a30 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61  2()] (and its va
21a40 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69  riants) or [sqli
21a50 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64  te3_reset()] and
21a60 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69  .** before [sqli
21a70 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
21a80 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
21a90 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
21aa0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
21ab0 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e  ] routine..** Un
21ac0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
21ad0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
21ae0 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
21af0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
21b00 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
21b10 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
21b20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66  an error code if
21b30 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65  .** anything goe
21b40 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54  s wrong.  [SQLIT
21b50 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
21b60 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
21b70 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
21b80 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
21b90 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20   [SQLITE_NOMEM] 
21ba0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
21bb0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
21bc0 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
21bd0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
21be0 6e 65 64 20 69 66 20 74 68 65 73 65 20 72 6f 75  ned if these rou
21bf0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
21c00 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c   on a.** virtual
21c10 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20 69 73   machine that is
21c20 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65   the wrong state
21c30 20 6f 72 20 77 68 69 63 68 20 68 61 73 20 61 6c   or which has al
21c40 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c  ready been final
21c50 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69  ized..** Detecti
21c60 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69 73 20  on of misuse is 
21c70 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 70  unreliable.  App
21c80 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
21c90 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f   not depend.** o
21ca0 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  n SQLITE_MISUSE 
21cb0 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 45  returns.  SQLITE
21cc0 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74 65 6e  _MISUSE is inten
21cd0 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ded to indicate 
21ce0 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 72  a.** a logic err
21cf0 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c 69 63  or in the applic
21d00 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 76  ation.  Future v
21d10 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
21d20 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63  e might.** panic
21d30 20 72 61 74 68 65 72 20 74 68 61 6e 20 72 65 74   rather than ret
21d40 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
21d50 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  E..**.** See als
21d60 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
21d70 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
21d80 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
21d90 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
21da0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
21db0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
21dc0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
21dd0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
21de0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 36 7d 20  .**.** {H13506} 
21df0 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65 6d 65  The [SQL stateme
21e00 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 72 65 63  nt compiler] rec
21e10 6f 67 6e 69 7a 65 73 20 74 6f 6b 65 6e 73 20 6f  ognizes tokens o
21e20 66 20 74 68 65 20 66 6f 72 6d 73 0a 2a 2a 20 20  f the forms.**  
21e30 20 20 20 20 20 20 20 20 22 3f 22 2c 20 22 3f 4e          "?", "?N
21e40 4e 4e 22 2c 20 22 24 56 56 56 22 2c 20 22 3a 56  NN", "$VVV", ":V
21e50 56 56 22 2c 20 61 6e 64 20 22 40 56 56 56 22 20  VV", and "@VVV" 
21e60 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  as SQL parameter
21e70 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  s,.**          w
21e80 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e 79 20  here NNN is any 
21e90 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20  sequence of one 
21ea0 6f 72 20 6d 6f 72 65 20 64 69 67 69 74 73 0a 2a  or more digits.*
21eb0 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 77  *          and w
21ec0 68 65 72 65 20 56 56 56 20 69 73 20 61 6e 79 20  here VVV is any 
21ed0 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20  sequence of one 
21ee0 6f 72 20 6d 6f 72 65 20 61 6c 70 68 61 6e 75 6d  or more alphanum
21ef0 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20  eric.**         
21f00 20 63 68 61 72 61 63 74 65 72 73 20 6f 72 20 22   characters or "
21f10 3a 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66  ::" optionally f
21f20 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20 73 74 72  ollowed by a str
21f30 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a  ing containing.*
21f40 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20 73 70  *          no sp
21f50 61 63 65 73 20 61 6e 64 20 63 6f 6e 74 61 69 6e  aces and contain
21f60 65 64 20 77 69 74 68 69 6e 20 70 61 72 65 6e 74  ed within parent
21f70 68 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  heses..**.** {H1
21f80 33 35 30 39 7d 20 54 68 65 20 69 6e 69 74 69 61  3509} The initia
21f90 6c 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51  l value of an SQ
21fa0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  L parameter is N
21fb0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  ULL..**.** {H135
21fc0 31 32 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66  12} The index of
21fd0 20 61 6e 20 22 3f 22 20 53 51 4c 20 70 61 72 61   an "?" SQL para
21fe0 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6c 61 72  meter is one lar
21ff0 67 65 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20  ger than the.** 
22000 20 20 20 20 20 20 20 20 20 6c 61 72 67 65 73 74           largest
22010 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61   index of SQL pa
22020 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 6c  rameter to the l
22030 65 66 74 2c 20 6f 72 20 31 20 69 66 0a 2a 2a 20  eft, or 1 if.** 
22040 20 20 20 20 20 20 20 20 20 74 68 65 20 22 3f 22           the "?"
22050 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74   is the leftmost
22060 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 2e 0a   SQL parameter..
22070 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 35 7d 20 54  **.** {H13515} T
22080 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22  he index of an "
22090 3f 4e 4e 4e 22 20 53 51 4c 20 70 61 72 61 6d 65  ?NNN" SQL parame
220a0 74 65 72 20 69 73 20 74 68 65 20 69 6e 74 65 67  ter is the integ
220b0 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48  er NNN..**.** {H
220c0 31 33 35 31 38 7d 20 54 68 65 20 69 6e 64 65 78  13518} The index
220d0 20 6f 66 20 61 6e 20 22 3a 56 56 56 22 2c 20 22   of an ":VVV", "
220e0 24 56 56 56 22 2c 20 6f 72 20 22 40 56 56 56 22  $VVV", or "@VVV"
220f0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
22100 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
22110 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 69 6e  e same as the in
22120 64 65 78 20 6f 66 20 6c 65 66 74 6d 6f 73 74 20  dex of leftmost 
22130 6f 63 63 75 72 72 65 6e 63 65 73 20 6f 66 20 74  occurrences of t
22140 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he same.**      
22150 20 20 20 20 70 61 72 61 6d 65 74 65 72 2c 20 6f      parameter, o
22160 72 20 6f 6e 65 20 6d 6f 72 65 20 74 68 61 6e 20  r one more than 
22170 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65  the largest inde
22180 78 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20 20 20  x over all.**   
22190 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
221a0 73 20 74 6f 20 74 68 65 20 6c 65 66 74 20 69 66  s to the left if
221b0 20 74 68 69 73 20 69 73 20 74 68 65 20 66 69 72   this is the fir
221c0 73 74 20 6f 63 63 75 72 72 65 6e 63 65 0a 2a 2a  st occurrence.**
221d0 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 69            of thi
221e0 73 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20  s parameter, or 
221f0 31 20 69 66 20 74 68 69 73 20 69 73 20 74 68 65  1 if this is the
22200 20 6c 65 66 74 6d 6f 73 74 20 70 61 72 61 6d 65   leftmost parame
22210 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  ter..**.** {H135
22220 32 31 7d 20 54 68 65 20 5b 53 51 4c 20 73 74 61  21} The [SQL sta
22230 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d  tement compiler]
22240 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 5b   fails with an [
22250 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 0a 2a 2a  SQLITE_RANGE].**
22260 20 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20            error 
22270 69 66 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  if the index of 
22280 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
22290 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 31 0a   is less than 1.
222a0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 67  **          or g
222b0 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
222c0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 53 51 4c  compile-time SQL
222d0 49 54 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45  ITE_MAX_VARIABLE
222e0 5f 4e 55 4d 42 45 52 0a 2a 2a 20 20 20 20 20 20  _NUMBER.**      
222f0 20 20 20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a      parameter..*
22300 2a 0a 2a 2a 20 7b 48 31 33 35 32 34 7d 20 43 61  *.** {H13524} Ca
22310 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
22320 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69  bind_text | sqli
22330 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e  te3_bind(S,N,V,.
22340 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
22350 20 61 73 73 6f 63 69 61 74 65 20 74 68 65 20 76   associate the v
22360 61 6c 75 65 20 56 20 77 69 74 68 20 61 6c 6c 20  alue V with all 
22370 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 68  SQL parameters h
22380 61 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20  aving an.**     
22390 20 20 20 20 20 69 6e 64 65 78 20 6f 66 20 4e 20       index of N 
223a0 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
223b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
223c0 2a 0a 2a 2a 20 7b 48 31 33 35 32 37 7d 20 43 61  *.** {H13527} Ca
223d0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
223e0 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69  bind_text | sqli
223f0 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e  te3_bind(S,N,...
22400 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
22410 76 65 72 72 69 64 65 20 70 72 69 6f 72 20 63 61  verride prior ca
22420 6c 6c 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  lls with the sam
22430 65 20 76 61 6c 75 65 73 20 6f 66 20 53 20 61 6e  e values of S an
22440 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  d N..**.** {H135
22450 33 30 7d 20 42 69 6e 64 69 6e 67 73 20 65 73 74  30} Bindings est
22460 61 62 6c 69 73 68 65 64 20 62 79 20 5b 73 71 6c  ablished by [sql
22470 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
22480 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c   sqlite3_bind(S,
22490 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
224a0 20 20 70 65 72 73 69 73 74 20 61 63 72 6f 73 73    persist across
224b0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
224c0 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a  e3_reset(S)]..**
224d0 0a 2a 2a 20 7b 48 31 33 35 33 33 7d 20 49 6e 20  .** {H13533} In 
224e0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
224f0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c  3_bind_blob(S,N,
22500 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,L,D)],.**     
22510 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
22520 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c  nd_text(S,N,V,L,
22530 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
22540 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
22550 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
22560 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64  ,D)] SQLite bind
22570 73 20 74 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a  s the first L.**
22580 20 20 20 20 20 20 20 20 20 20 62 79 74 65 73 20            bytes 
22590 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
225a0 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
225b0 20 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a   by V, when L.**
225c0 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e            is non
225d0 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a  -negative..**.**
225e0 20 7b 48 31 33 35 33 36 7d 20 49 6e 20 63 61 6c   {H13536} In cal
225f0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
22600 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c  ind_text(S,N,V,L
22610 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  ,D)] or.**      
22620 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
22630 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
22640 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64  ,D)] SQLite bind
22650 73 20 63 68 61 72 61 63 74 65 72 73 0a 2a 2a 20  s characters.** 
22660 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 56 20           from V 
22670 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
22680 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
22690 20 77 68 65 6e 20 4c 20 69 73 20 6e 65 67 61 74   when L is negat
226a0 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  ive..**.** {H135
226b0 33 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  39} In calls to 
226c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
226d0 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a  ob(S,N,V,L,D)],.
226e0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
226f0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53  ite3_bind_text(S
22700 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a  ,N,V,L,D)], or.*
22710 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
22720 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
22730 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e  S,N,V,L,D)] when
22740 20 44 20 69 73 20 74 68 65 20 73 70 65 63 69 61   D is the specia
22750 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  l.**          co
22760 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53  nstant [SQLITE_S
22770 54 41 54 49 43 5d 2c 20 53 51 4c 69 74 65 20 61  TATIC], SQLite a
22780 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
22790 76 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20 20  value V.**      
227a0 20 20 20 20 69 73 20 68 65 6c 64 20 69 6e 20 73      is held in s
227b0 74 61 74 69 63 20 75 6e 6d 61 6e 61 67 65 64 20  tatic unmanaged 
227c0 73 70 61 63 65 20 74 68 61 74 20 77 69 6c 6c 20  space that will 
227d0 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20  not change.**   
227e0 20 20 20 20 20 20 20 64 75 72 69 6e 67 20 74 68         during th
227f0 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68  e lifetime of th
22800 65 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e binding..**.**
22810 20 7b 48 31 33 35 34 32 7d 20 49 6e 20 63 61 6c   {H13542} In cal
22820 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
22830 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c  ind_blob(S,N,V,L
22840 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
22850 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
22860 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
22870 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
22880 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
22890 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29  ext16(S,N,V,L,D)
228a0 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65 20  ] when D is the 
228b0 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20  special.**      
228c0 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51      constant [SQ
228d0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
228e0 20 74 68 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b   the routine mak
228f0 65 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  es a.**         
22900 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
22910 20 74 68 65 20 76 61 6c 75 65 20 56 20 62 65 66   the value V bef
22920 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a  ore it returns..
22930 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 35 7d 20 49  **.** {H13545} I
22940 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
22950 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c  te3_bind_blob(S,
22960 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20  N,V,L,D)],.**   
22970 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
22980 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
22990 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  L,D)], or.**    
229a0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
229b0 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56  ind_text16(S,N,V
229c0 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73  ,L,D)] when D is
229d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
229e0 20 20 20 20 20 20 20 20 20 20 61 20 66 75 6e 63            a func
229f0 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e 76  tion, SQLite inv
22a00 6f 6b 65 73 20 74 68 61 74 20 66 75 6e 63 74 69  okes that functi
22a10 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79 20 74 68  on to destroy th
22a20 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  e.**          va
22a30 6c 75 65 20 56 20 61 66 74 65 72 20 69 74 20 68  lue V after it h
22a40 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
22a50 67 20 74 68 65 20 76 61 6c 75 65 20 56 2e 0a 2a  g the value V..*
22a60 2a 0a 2a 2a 20 7b 48 31 33 35 34 38 7d 20 49 6e  *.** {H13548} In
22a70 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
22a80 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
22a90 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 76  (S,N,V,L)] the v
22aa0 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 20  alue bound.**   
22ab0 20 20 20 20 20 20 20 69 73 20 61 20 42 4c 4f 42         is a BLOB
22ac0 20 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f 72 20   of L bytes, or 
22ad0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
22ae0 4f 42 20 69 66 20 4c 20 69 73 20 6e 65 67 61 74  OB if L is negat
22af0 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  ive..**.** {H135
22b00 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  51} In calls to 
22b10 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
22b20 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65 20  lue(S,N,V)] the 
22b30 56 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a 2a  V argument may.*
22b40 2a 20 20 20 20 20 20 20 20 20 20 62 65 20 65 69  *          be ei
22b50 74 68 65 72 20 61 20 5b 70 72 6f 74 65 63 74 65  ther a [protecte
22b60 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
22b70 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a 2a   object or an.**
22b80 20 20 20 20 20 20 20 20 20 20 5b 75 6e 70 72 6f            [unpro
22b90 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
22ba0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  alue] object..*/
22bb0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
22bc0 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
22bd0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
22be0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
22bf0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
22c00 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
22c10 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
22c20 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
22c30 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
22c40 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
22c50 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
22c60 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
22c70 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
22c80 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
22c90 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
22ca0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
22cb0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
22cc0 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
22cd0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
22ce0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
22cf0 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
22d00 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
22d10 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
22d20 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
22d30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
22d40 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
22d50 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
22d60 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
22d70 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
22d80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
22d90 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
22da0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
22db0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
22dc0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
22dd0 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
22de0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22df0 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
22e00 61 72 61 6d 65 74 65 72 73 20 7b 48 31 33 36 30  arameters {H1360
22e10 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a  0} <S70300>.**.*
22e20 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63  * This routine c
22e30 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
22e40 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
22e50 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
22e60 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
22e70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
22e80 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
22e90 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
22ea0 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
22eb0 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
22ec0 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
22ed0 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
22ee0 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
22ef0 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
22f00 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
22f10 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
22f20 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
22f30 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
22f40 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ime..**.** This 
22f50 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
22f60 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
22f70 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
22f80 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
22f90 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
22fa0 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
22fb0 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
22fc0 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
22fd0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
22fe0 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
22ff0 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
23000 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72  s of the ?NNN ar
23010 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
23020 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
23030 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20  the list..**.** 
23040 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
23050 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
23060 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
23070 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
23080 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
23090 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
230a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
230b0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _index()]..**.**
230c0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
230d0 2a 2a 20 7b 48 31 33 36 30 31 7d 20 54 68 65 20  ** {H13601} The 
230e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
230f0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 53 29  rameter_count(S)
23100 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
23110 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
23120 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65  the largest inde
23130 78 20 6f 66 20 61 6c 6c 20 53 51 4c 20 70 61 72  x of all SQL par
23140 61 6d 65 74 65 72 73 20 69 6e 20 74 68 65 0a 2a  ameters in the.*
23150 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
23160 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
23170 53 2c 20 6f 72 20 30 20 69 66 20 53 20 63 6f 6e  S, or 0 if S con
23180 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72  tains no SQL par
23190 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20  ameters..*/.int 
231a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
231b0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c  ameter_count(sql
231c0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
231d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
231e0 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72  me Of A Host Par
231f0 61 6d 65 74 65 72 20 7b 48 31 33 36 32 30 7d 20  ameter {H13620} 
23200 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S70300>.**.** T
23210 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
23220 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
23230 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
23240 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61   n-th.** [SQL pa
23250 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 20 5b 70  rameter] in a [p
23260 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23270 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  t]..** SQL param
23280 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
23290 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  m "?NNN" or ":AA
232a0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
232b0 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61  "$AAA".** have a
232c0 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74   name which is t
232d0 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22  he string "?NNN"
232e0 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
232f0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
23300 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  * respectively..
23310 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
23320 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
23330 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
23340 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e   or "?".** is in
23350 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
23360 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50  f the name..** P
23370 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
23380 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
23390 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
233a0 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
233b0 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c  me.** and are al
233c0 73 6f 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  so referred to a
233d0 73 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  s "anonymous par
233e0 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
233f0 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
23400 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
23410 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
23420 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  0..**.** If the 
23430 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f  value n is out o
23440 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
23450 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e n-th parameter
23460 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
23470 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
23480 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74  turned.  The ret
23490 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
234a0 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
234b0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
234c0 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
234d0 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
234e0 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
234f0 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
23500 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
23510 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
23520 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
23530 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
23540 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
23550 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
23560 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
23570 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
23580 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
23590 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
235a0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
235b0 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ndex()]..**.** I
235c0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
235d0 20 7b 48 31 33 36 32 31 7d 20 54 68 65 20 5b 73   {H13621} The [s
235e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
235f0 6d 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d  meter_name(S,N)]
23600 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
23610 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ns.**          a
23620 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
23630 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   of the name of 
23640 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
23650 72 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  r in.**         
23660 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
23670 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 76 69  tatement] S havi
23680 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a  ng index N, or.*
23690 2a 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  *          NULL 
236a0 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 53  if there is no S
236b0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 77 69 74  QL parameter wit
236c0 68 20 69 6e 64 65 78 20 4e 20 6f 72 20 69 66 20  h index N or if 
236d0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
236e0 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69  parameter with i
236f0 6e 64 65 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f  ndex N is an ano
23700 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
23710 20 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63   "?"..*/.const c
23720 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
23730 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
23740 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
23750 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
23760 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
23770 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
23780 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48   A Given Name {H
23790 31 33 36 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a  13640} <S70300>.
237a0 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65  **.** Return the
237b0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
237c0 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
237d0 20 69 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a   its name.  The.
237e0 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
237f0 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
23800 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
23810 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
23820 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
23830 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
23840 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41  ite3_bind()].  A
23850 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
23860 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
23870 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
23880 20 66 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 72   found.  The par
23890 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
238a0 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
238b0 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
238c0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
238d0 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
238e0 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
238f0 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
23900 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
23910 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
23920 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
23930 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
23940 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
23950 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
23960 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
23970 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
23980 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
23990 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  dex()]..**.** IN
239a0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
239b0 7b 48 31 33 36 34 31 7d 20 54 68 65 20 5b 73 71  {H13641} The [sq
239c0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
239d0 65 74 65 72 5f 69 6e 64 65 78 28 53 2c 4e 29 5d  eter_index(S,N)]
239e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
239f0 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ns.**          t
23a00 68 65 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20  he index of SQL 
23a10 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
23a20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23a30 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ment].**        
23a40 20 20 53 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d    S whose name m
23a50 61 74 63 68 65 73 20 74 68 65 20 55 54 46 2d 38  atches the UTF-8
23a60 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20   string N, or 0 
23a70 69 66 20 74 68 65 72 65 20 69 73 0a 2a 2a 20 20  if there is.**  
23a80 20 20 20 20 20 20 20 20 6e 6f 20 6d 61 74 63 68          no match
23a90 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
23aa0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
23ab0 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
23ac0 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
23ad0 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
23ae0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
23af0 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
23b00 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
23b10 6d 65 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c 53  ment {H13660} <S
23b20 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e  70300>.**.** Con
23b30 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74  trary to the int
23b40 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20  uition of many, 
23b50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
23b60 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74  ] does not reset
23b70 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
23b80 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e  _bind_blob | bin
23b90 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65  dings] on a [pre
23ba0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23bb0 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f  ..** Use this ro
23bc0 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61  utine to reset a
23bd0 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  ll host paramete
23be0 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  rs to NULL..**.*
23bf0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
23c00 0a 2a 2a 20 7b 48 31 33 36 36 31 7d 20 54 68 65  .** {H13661} The
23c10 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
23c20 62 69 6e 64 69 6e 67 73 28 53 29 5d 20 69 6e 74  bindings(S)] int
23c30 65 72 66 61 63 65 20 72 65 73 65 74 73 20 61 6c  erface resets al
23c40 6c 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20  l SQL.**        
23c50 20 20 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64    parameter bind
23c60 69 6e 67 73 20 69 6e 20 74 68 65 20 5b 70 72 65  ings in the [pre
23c70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23c80 20 53 20 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e   S back to NULL.
23c90 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
23ca0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
23cb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
23cc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23cd0 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
23ce0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
23cf0 74 20 7b 48 31 33 37 31 30 7d 20 3c 53 31 30 37  t {H13710} <S107
23d00 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  00>.**.** Return
23d10 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
23d20 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
23d30 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
23d40 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
23d50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23d60 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  . This routine r
23d70 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d  eturns 0 if pStm
23d80 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73  t is an SQL.** s
23d90 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
23da0 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
23db0 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
23dc0 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
23dd0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
23de0 2a 2a 0a 2a 2a 20 7b 48 31 33 37 31 31 7d 20 54  **.** {H13711} T
23df0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
23e00 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74  mn_count(S)] int
23e10 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
23e20 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
23e30 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73           columns
23e40 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
23e50 65 74 20 67 65 6e 65 72 61 74 65 64 20 62 79 20  et generated by 
23e60 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
23e70 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20  atement] S,.**  
23e80 20 20 20 20 20 20 20 20 6f 72 20 30 20 69 66 20          or 0 if 
23e90 53 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72  S does not gener
23ea0 61 74 65 20 61 20 72 65 73 75 6c 74 20 73 65 74  ate a result set
23eb0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
23ec0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
23ed0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
23ee0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
23ef0 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
23f00 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
23f10 74 20 7b 48 31 33 37 32 30 7d 20 3c 53 31 30 37  t {H13720} <S107
23f20 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
23f30 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
23f40 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
23f50 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
23f60 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
23f70 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
23f80 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
23f90 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  ement.  The sqli
23fa0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
23fb0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
23fc0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
23fd0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
23fe0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
23ff0 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
24000 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
24010 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
24020 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
24030 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
24040 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20  16 string.  The 
24050 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
24060 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
24070 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
24080 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
24090 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
240a0 65 6d 65 6e 74 2e 20 54 68 65 20 73 65 63 6f 6e  ement. The secon
240b0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
240c0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d  he.** column num
240d0 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f  ber.  The leftmo
240e0 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
240f0 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ber 0..**.** The
24100 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
24110 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
24120 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
24130 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
24140 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
24150 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
24160 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
24170 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
24180 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
24190 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
241a0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
241b0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
241c0 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
241d0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74  ..**.** If sqlit
241e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
241f0 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
24200 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
24210 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
24220 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
24230 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
24240 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
24250 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
24260 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
24270 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
24280 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
24290 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
242a0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
242b0 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
242c0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
242d0 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
242e0 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
242f0 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
24300 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
24310 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
24320 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
24330 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
24340 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
24350 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
24360 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20  the next..**.** 
24370 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
24380 2a 20 7b 48 31 33 37 32 31 7d 20 41 20 73 75 63  * {H13721} A suc
24390 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69  cessful invocati
243a0 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
243b0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53  e3_column_name(S
243c0 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,N)].**         
243d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
243e0 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ns the name of t
243f0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77  he Nth column (w
24400 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20  here 0 is.**    
24410 20 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f        the leftmo
24420 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74  st column) for t
24430 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
24440 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
24450 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24460 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72  ment] S as a zer
24470 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
24480 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
24490 20 7b 48 31 33 37 32 33 7d 20 41 20 73 75 63 63   {H13723} A succ
244a0 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
244b0 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
244c0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
244d0 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,N)].**        
244e0 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75    interface retu
244f0 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  rns the name of 
24500 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28  the Nth column (
24510 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20  where 0 is.**   
24520 20 20 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d         the leftm
24530 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20  ost column) for 
24540 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
24550 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
24560 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
24570 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65  ement] S as a ze
24580 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
24590 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 20  F-16 string.**  
245a0 20 20 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e          in the n
245b0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
245c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 34 7d  ..**.** {H13724}
245d0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
245e0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64  lumn_name()] and
245f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24600 5f 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20  _name16()].**   
24610 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
24620 73 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20  s return a NULL 
24630 70 6f 69 6e 74 65 72 20 69 66 20 74 68 65 79 20  pointer if they 
24640 61 72 65 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a  are unable to.**
24650 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61            alloca
24660 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  te memory to hol
24670 64 20 74 68 65 69 72 20 6e 6f 72 6d 61 6c 20 72  d their normal r
24680 65 74 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a  eturn strings..*
24690 2a 0a 2a 2a 20 7b 48 31 33 37 32 35 7d 20 49 66  *.** {H13725} If
246a0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
246b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
246c0 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f  umn_name(S,N)] o
246d0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
246e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
246f0 6d 65 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75  me16(S,N)] is ou
24700 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 6e  t of range, then
24710 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
24720 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75   interfaces retu
24730 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  rn a NULL pointe
24740 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 36  r..**.** {H13726
24750 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  } The strings re
24760 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
24770 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53  e3_column_name(S
24780 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ,N)] and.**     
24790 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
247a0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  lumn_name16(S,N)
247b0 5d 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  ] are valid unti
247c0 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20  l the next.**   
247d0 20 20 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65         call to e
247e0 69 74 68 65 72 20 72 6f 75 74 69 6e 65 20 77 69  ither routine wi
247f0 74 68 20 74 68 65 20 73 61 6d 65 20 53 20 61 6e  th the same S an
24800 64 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  d N parameters.*
24810 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e  *          or un
24820 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  til [sqlite3_fin
24830 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c  alize(S)] is cal
24840 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  led..**.** {H137
24850 32 37 7d 20 57 68 65 6e 20 61 20 72 65 73 75 6c  27} When a resul
24860 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53  t column of a [S
24870 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
24880 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20   contains.**    
24890 20 20 20 20 20 20 61 6e 20 41 53 20 63 6c 61 75        an AS clau
248a0 73 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  se, the name of 
248b0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  that column is t
248c0 68 65 20 69 64 65 6e 74 69 66 69 65 72 0a 2a 2a  he identifier.**
248d0 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65            to the
248e0 20 72 69 67 68 74 20 6f 66 20 74 68 65 20 41 53   right of the AS
248f0 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e   keyword..*/.con
24900 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
24910 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
24920 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
24930 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  N);.const void *
24940 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
24950 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
24960 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a  mt*, int N);../*
24970 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f  .** CAPI3REF: So
24980 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20  urce Of Data In 
24990 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b  A Query Result {
249a0 48 31 33 37 34 30 7d 20 3c 53 31 30 37 30 30 3e  H13740} <S10700>
249b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
249c0 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
249d0 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
249e0 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f  ne what column o
249f0 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20  f what.** table 
24a00 69 6e 20 77 68 69 63 68 20 64 61 74 61 62 61 73  in which databas
24a10 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20  e a result of a 
24a20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
24a30 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a  nt comes from..*
24a40 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * The name of th
24a50 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
24a60 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
24a70 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
24a80 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
24a90 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
24aa0 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62  ing.  The _datab
24ab0 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
24ac0 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
24ad0 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
24ae0 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
24af0 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
24b00 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
24b10 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
24b20 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
24b30 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68  lumn name..** Th
24b40 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
24b50 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
24b60 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
24b70 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
24b80 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
24b90 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
24ba0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
24bb0 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
24bc0 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
24bd0 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
24be0 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
24bf0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65  ..**.** The name
24c00 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
24c10 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
24c20 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
24c30 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
24c40 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
24c50 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  mn..**.** The fi
24c60 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
24c70 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
24c80 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  lls is a [prepar
24c90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
24ca0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
24cb0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
24cc0 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
24cd0 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
24ce0 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61  ed by.** the sta
24cf0 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
24d00 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
24d10 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
24d20 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74  .**.** If the Nt
24d30 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
24d40 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
24d50 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
24d60 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
24d70 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
24d80 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
24d90 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
24da0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
24db0 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65  .** NULL.  These
24dc0 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
24dd0 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
24de0 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
24df0 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
24e00 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69  occurs.  Otherwi
24e10 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
24e20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
24e30 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
24e40 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20  e, table.** and 
24e50 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
24e60 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
24e70 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
24e80 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74  om..**.** As wit
24e90 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
24ea0 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70  te APIs, those p
24eb0 6f 73 74 66 69 78 65 64 20 77 69 74 68 20 22 31  ostfixed with "1
24ec0 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
24ed0 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
24ee0 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66  ngs, the other f
24ef0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
24f00 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  UTF-8. {END}.**.
24f10 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20 61 72  ** These APIs ar
24f20 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
24f30 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
24f40 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
24f50 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
24f60 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
24f70 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
24f80 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64  ocessor symbol d
24f90 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41  efined..**.** {A
24fa0 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f  13751}.** If two
24fb0 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
24fc0 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
24fd0 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
24fe0 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
24ff0 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
25000 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
25010 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
25020 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
25030 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
25040 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
25050 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
25060 2a 20 7b 48 31 33 37 34 31 7d 20 54 68 65 20 5b  * {H13741} The [
25070 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
25080 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e  atabase_name(S,N
25090 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
250a0 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
250b0 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
250c0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
250d0 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  d name of the da
250e0 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63  tabase from whic
250f0 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  h the.**        
25100 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c    Nth result col
25110 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70  umn of the [prep
25120 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
25130 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a  S is extracted,.
25140 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e  **          or N
25150 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
25160 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20  olumn of S is a 
25170 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
25180 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  on.**          o
25190 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
251a0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
251b0 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
251c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 32 7d  ..**.** {H13742}
251d0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [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 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  me16(S,N)] inter
25200 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
25210 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
25220 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76  the UTF-16 nativ
25230 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72  e byte order zer
25240 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
25250 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
25260 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72  e.**          fr
25270 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74 68  om which the Nth
25280 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
25290 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
252a0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a  statement] S is.
252b0 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 74 72  **          extr
252c0 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69  acted, or NULL i
252d0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
252e0 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72   of S is a gener
252f0 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  al expression.**
25300 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20            or if 
25310 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
25320 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f  te memory to sto
25330 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a  re the name..**.
25340 2a 2a 20 7b 48 31 33 37 34 33 7d 20 54 68 65 20  ** {H13743} The 
25350 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
25360 74 61 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d  table_name(S,N)]
25370 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
25380 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
25390 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20        the UTF-8 
253a0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
253b0 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c  name of the tabl
253c0 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  e from which the
253d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
253e0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f   result column o
253f0 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
25400 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20  statement] S is 
25410 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20  extracted,.**   
25420 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69         or NULL i
25430 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
25440 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72   of S is a gener
25450 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  al expression.**
25460 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20            or if 
25470 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
25480 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f  te memory to sto
25490 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a  re the name..**.
254a0 2a 2a 20 7b 48 31 33 37 34 34 7d 20 54 68 65 20  ** {H13744} The 
254b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
254c0 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e  table_name16(S,N
254d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
254e0 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
254f0 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
25500 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
25510 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  rder zero-termin
25520 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  ated name of the
25530 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20   table.**       
25540 20 20 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68     from which th
25550 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
25560 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70  umn of the [prep
25570 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
25580 53 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  S is.**         
25590 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e   extracted, or N
255a0 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63  ULL if the Nth c
255b0 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20  olumn of S is a 
255c0 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69  general expressi
255d0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  on.**          o
255e0 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61  r if unable to a
255f0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
25600 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65  o store the name
25610 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 35 7d  ..**.** {H13745}
25620 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
25630 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
25640 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
25650 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
25660 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
25670 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
25680 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68  nated name of th
25690 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66  e table column f
256a0 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a  rom which the.**
256b0 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65            Nth re
256c0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  sult column of t
256d0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
256e0 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74  tement] S is ext
256f0 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20  racted,.**      
25700 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74      or NULL if t
25710 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
25720 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20   S is a general 
25730 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20  expression.**   
25740 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61         or if una
25750 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
25760 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20  memory to store 
25770 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  the name..**.** 
25780 7b 48 31 33 37 34 36 7d 20 54 68 65 20 5b 73 71  {H13746} The [sq
25790 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
257a0 67 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  gin_name16(S,N)]
257b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
257c0 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
257d0 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36        the UTF-16
257e0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
257f0 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  er zero-terminat
25800 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74  ed name of the t
25810 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  able.**         
25820 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69   column from whi
25830 63 68 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ch the Nth resul
25840 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  t column of the.
25850 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
25860 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25870 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c   S is extracted,
25880 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
25890 4e 74 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20  Nth column.**   
258a0 20 20 20 20 20 20 20 6f 66 20 53 20 69 73 20 61         of S is a
258b0 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73   general express
258c0 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65  ion or if unable
258d0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
258e0 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ory.**          
258f0 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d  to store the nam
25900 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 38  e..**.** {H13748
25910 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  } The return val
25920 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20  ues from.**     
25930 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
25940 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
25950 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
25960 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
25970 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
25980 20 76 61 6c 69 64 20 66 6f 72 20 74 68 65 20 6c   valid for the l
25990 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 5b  ifetime of the [
259a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
259b0 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nt].**          
259c0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 65 6e 63  or until the enc
259d0 6f 64 69 6e 67 20 69 73 20 63 68 61 6e 67 65 64  oding is changed
259e0 20 62 79 20 61 6e 6f 74 68 65 72 20 6d 65 74 61   by another meta
259f0 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  data.**         
25a00 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20   interface call 
25a10 66 6f 72 20 74 68 65 20 73 61 6d 65 20 70 72 65  for the same pre
25a20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
25a30 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
25a40 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a  * ASSUMPTIONS:.*
25a50 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 20 49 66  *.** {A13751} If
25a60 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
25a70 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
25a80 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20   more.**        
25a90 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
25aa0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
25ab0 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
25ac0 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
25ad0 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 74 68            for th
25ae0 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
25af0 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
25b00 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
25b10 20 20 20 20 20 20 20 20 20 20 61 74 20 74 68 65            at the
25b20 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
25b30 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
25b40 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f  undefined..*/.co
25b50 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
25b60 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
25b70 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
25b80 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
25b90 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
25ba0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
25bb0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
25bc0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
25bd0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
25be0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
25bf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
25c00 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
25c10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
25c20 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  able_name16(sqli
25c30 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
25c40 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
25c50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
25c60 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
25c70 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
25c80 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
25c90 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
25ca0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
25cb0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
25cc0 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
25cd0 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20  d Datatype Of A 
25ce0 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31  Query Result {H1
25cf0 33 37 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  3760} <S10700>.*
25d00 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
25d10 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70  arameter is a [p
25d20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25d30 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73  t]..** If this s
25d40 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53  tatement is a [S
25d50 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
25d60 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c   and the Nth col
25d70 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  umn of the.** re
25d80 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65  turned result se
25d90 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43  t of that [SELEC
25da0 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f  T] is a table co
25db0 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20  lumn (not an.** 
25dc0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
25dd0 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65  bquery) then the
25de0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f   declared type o
25df0 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63  f the table.** c
25e00 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65  olumn is returne
25e10 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68 20 63  d.  If the Nth c
25e20 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
25e30 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
25e40 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
25e50 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
25e60 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
25e70 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65  returned..** The
25e80 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
25e90 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
25ea0 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a   encoded. {END}.
25eb0 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
25ec0 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74  e, given the dat
25ed0 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a  abase schema:.**
25ee0 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45  .** CREATE TABLE
25ef0 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b   t1(c1 VARIANT);
25f00 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66  .**.** and the f
25f10 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65  ollowing stateme
25f20 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
25f30 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20  d:.**.** SELECT 
25f40 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20  c1 + 1, c1 FROM 
25f50 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72  t1;.**.** this r
25f60 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74  outine would ret
25f70 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22  urn the string "
25f80 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65  VARIANT" for the
25f90 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a   second result.*
25fa0 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c  * column (i==1),
25fb0 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   and a NULL poin
25fc0 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73  ter for the firs
25fd0 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  t result column 
25fe0 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51  (i==0)..**.** SQ
25ff0 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
26000 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
26010 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61  g.  So just beca
26020 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
26030 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
26040 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
26050 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
26060 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
26070 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
26080 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
26090 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
260a0 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
260b0 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
260c0 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
260d0 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
260e0 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79 70 65  ot static.  Type
260f0 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
26100 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
26110 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
26120 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
26130 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
26140 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
26150 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
26160 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 31 7d  :.**.** {H13761}
26170 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63    A successful c
26180 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
26190 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
261a0 53 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 0a  S,N)] returns a.
261b0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 7a 65 72  **           zer
261c0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
261d0 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  -8 string contai
261e0 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61 72 65  ning the declare
261f0 64 20 64 61 74 61 74 79 70 65 0a 2a 2a 20 20 20  d datatype.**   
26200 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 74          of the t
26210 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
26220 20 61 70 70 65 61 72 73 20 61 73 20 74 68 65 20   appears as the 
26230 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62  Nth column (numb
26240 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ered.**         
26250 20 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65    from 0) of the
26260 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74   result set to t
26270 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
26280 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a  tement] S..**.**
26290 20 7b 48 31 33 37 36 32 7d 20 20 41 20 73 75 63   {H13762}  A suc
262a0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
262b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
262c0 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d  decltype16(S,N)]
262d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
262e0 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72  turns a zero-ter
262f0 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e  minated UTF-16 n
26300 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
26310 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20   string.**      
26320 20 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20       containing 
26330 74 68 65 20 64 65 63 6c 61 72 65 64 20 64 61 74  the declared dat
26340 61 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62  atype of the tab
26350 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61  le column that a
26360 70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20  ppears.**       
26370 20 20 20 20 61 73 20 74 68 65 20 4e 74 68 20 63      as the Nth c
26380 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20  olumn (numbered 
26390 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72  from 0) of the r
263a0 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65  esult set to the
263b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70  .**           [p
263c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
263d0 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  t] S..**.** {H13
263e0 37 36 33 7d 20 20 49 66 20 4e 20 69 73 20 6c 65  763}  If N is le
263f0 73 73 20 74 68 61 6e 20 30 20 6f 72 20 4e 20 69  ss than 0 or N i
26400 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f  s greater than o
26410 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20  r equal to.**   
26420 20 20 20 20 20 20 20 20 74 68 65 20 6e 75 6d 62          the numb
26430 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
26440 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
26450 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20  tatement] S,.** 
26460 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20            or if 
26470 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
26480 66 20 53 20 69 73 20 61 6e 20 65 78 70 72 65 73  f S is an expres
26490 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
264a0 20 72 61 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   rather.**      
264b0 20 20 20 20 20 74 68 61 6e 20 61 20 74 61 62 6c       than a tabl
264c0 65 20 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69 66 20  e column, or if 
264d0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
264e0 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a 20 20  ion failure.**  
264f0 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 20           occurs 
26500 64 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20  during encoding 
26510 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74 68 65  conversions, the
26520 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63  n.**           c
26530 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
26540 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
26550 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  (S,N)] or.**    
26560 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
26570 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
26580 36 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 20 4e  6(S,N)] return N
26590 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ULL..*/.const ch
265a0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
265b0 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
265c0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
265d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
265e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
265f0 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
26600 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
26610 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
26620 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
26630 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d 20 3c 53  ment {H13200} <S
26640 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74  10000>.**.** Aft
26650 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
26660 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
26670 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
26680 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
26690 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
266a0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
266b0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
266c0 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
266d0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
266e0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
266f0 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
26700 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
26710 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
26720 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
26730 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
26740 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
26750 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
26760 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
26770 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
26780 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
26790 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
267a0 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
267b0 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
267c0 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
267d0 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
267e0 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
267f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26800 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
26810 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
26820 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
26830 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
26840 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
26850 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
26860 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
26870 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
26880 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
26890 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
268a0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
268b0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
268c0 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
268d0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
268e0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
268f0 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
26900 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
26910 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
26920 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
26930 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
26940 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
26950 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
26960 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
26970 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
26980 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57  TE_MISUSE]..** W
26990 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
269a0 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
269b0 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
269c0 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
269d0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
269e0 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
269f0 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
26a00 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  .**.** [SQLITE_B
26a10 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
26a20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
26a30 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
26a40 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
26a50 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
26a60 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
26a70 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20  ts job.  If the 
26a80 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
26a90 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
26aa0 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
26ab0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
26ac0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
26ad0 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
26ae0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
26af0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
26b00 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
26b10 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
26b20 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69  hin a.** explici
26b30 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
26b40 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
26b50 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
26b60 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
26b70 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
26b80 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
26b90 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
26ba0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
26bb0 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
26bc0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
26bd0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
26be0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
26bf0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
26c00 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
26c10 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
26c20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
26c30 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
26c40 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
26c50 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
26c60 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
26c70 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
26c80 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
26c90 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
26ca0 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
26cb0 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
26cc0 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
26cd0 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
26ce0 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
26cf0 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
26d00 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
26d10 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
26d20 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
26d30 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
26d40 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
26d50 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
26d60 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
26d70 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
26d80 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
26d90 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
26da0 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
26db0 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
26dc0 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
26dd0 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
26de0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
26df0 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
26e00 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
26e10 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
26e20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
26e30 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
26e40 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
26e50 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
26e60 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
26e70 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69  errmsg()]..** Wi
26e80 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
26e90 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
26ea0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
26eb0 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
26ec0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
26ed0 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
26ee0 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
26ef0 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
26f00 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
26f10 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
26f20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
26f30 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
26f40 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
26f50 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68  atement].  In th
26f60 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
26f70 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
26f80 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
26f90 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
26fa0 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
26fb0 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
26fc0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
26fd0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
26fe0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
26ff0 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
27000 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
27010 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
27020 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
27030 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
27040 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
27050 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
27060 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
27070 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
27080 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75  t had.** previou
27090 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
270a0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
270b0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
270c0 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
270d0 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
270e0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
270f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
27100 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
27110 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
27120 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
27130 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
27140 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
27150 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
27160 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63  /b> In the legac
27170 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
27180 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a   sqlite3_step().
27190 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  ** API always re
271a0 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
271b0 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c  error code, [SQL
271c0 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
271d0 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72  owing any.** err
271e0 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
271f0 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
27200 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
27210 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a    You must call.
27220 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
27230 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
27240 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
27250 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
27260 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63  e of the.** spec
27270 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
27280 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
27290 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
272a0 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
272b0 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
272c0 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
272d0 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
272e0 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
272f0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
27300 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
27310 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
27320 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
27330 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ** using either 
27340 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
27350 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
27360 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
27370 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
27380 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
27390 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
273a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
273b0 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66  pare16()] interf
273c0 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  aces,.** then th
273d0 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
273e0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72  [error codes] ar
273f0 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  e returned direc
27400 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  tly.** by sqlite
27410 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75  3_step().  The u
27420 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69  se of the "v2" i
27430 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
27440 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mmended..**.** I
27450 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
27460 20 7b 48 31 33 32 30 32 7d 20 20 49 66 20 74 68   {H13202}  If th
27470 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
27480 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65 61 64  ement] S is read
27490 79 20 74 6f 20 62 65 20 72 75 6e 2c 20 74 68 65  y to be run, the
274a0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  n.**           [
274b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
274c0 20 61 64 76 61 6e 63 65 73 20 74 68 61 74 20 70   advances that p
274d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
274e0 74 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20  t until.**      
274f0 20 20 20 20 20 63 6f 6d 70 6c 65 74 69 6f 6e 20       completion 
27500 6f 72 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72  or until it is r
27510 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 20 61  eady to return a
27520 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68  nother row of th
27530 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  e.**           r
27540 65 73 75 6c 74 20 73 65 74 2c 20 6f 72 20 75 6e  esult set, or un
27550 74 69 6c 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  til an [sqlite3_
27560 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65  interrupt | inte
27570 72 72 75 70 74 5d 0a 2a 2a 20 20 20 20 20 20 20  rrupt].**       
27580 20 20 20 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d      or a run-tim
27590 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
275a0 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 34 7d 20 20  **.** {H15304}  
275b0 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b  When a call to [
275c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
275d0 20 63 61 75 73 65 73 20 74 68 65 20 5b 70 72 65   causes the [pre
275e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
275f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 53 20  .**           S 
27600 74 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65  to run to comple
27610 74 69 6f 6e 2c 20 74 68 65 20 66 75 6e 63 74 69  tion, the functi
27620 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  on returns [SQLI
27630 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_DONE]..**.** 
27640 7b 48 31 35 33 30 36 7d 20 20 57 68 65 6e 20 61  {H15306}  When a
27650 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
27660 33 5f 73 74 65 70 28 53 29 5d 20 73 74 6f 70 73  3_step(S)] stops
27670 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 72   because it is r
27680 65 61 64 79 20 74 6f 0a 2a 2a 20 20 20 20 20 20  eady to.**      
27690 20 20 20 20 20 72 65 74 75 72 6e 20 61 6e 6f 74       return anot
276a0 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65 20 72  her row of the r
276b0 65 73 75 6c 74 20 73 65 74 2c 20 69 74 20 72 65  esult set, it re
276c0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f  turns [SQLITE_RO
276d0 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30  W]..**.** {H1530
276e0 38 7d 20 20 49 66 20 61 20 63 61 6c 6c 20 74 6f  8}  If a call to
276f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
27700 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e  )] encounters an
27710 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
27720 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
27730 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 20 6f 72   | interrupt] or
27740 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
27750 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  r,.**           
27760 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  it returns an ap
27770 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20  propriate error 
27780 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e 6f 74  code that is not
27790 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20   one of.**      
277a0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d       [SQLITE_OK]
277b0 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
277c0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
277d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 31 30 7d  ..**.** {H15310}
277e0 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33    If an [sqlite3
277f0 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74  _interrupt | int
27800 65 72 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e  errupt] or a run
27810 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20  -time error.**  
27820 20 20 20 20 20 20 20 20 20 6f 63 63 75 72 73 20           occurs 
27830 64 75 72 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  during a call to
27840 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
27850 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  )].**           
27860 66 6f 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  for a [prepared 
27870 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 63 72 65  statement] S cre
27880 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ated using.**   
27890 20 20 20 20 20 20 20 20 6c 65 67 61 63 79 20 69          legacy i
278a0 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
278b0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
278c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
278d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
278e0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 75  ()], then the fu
278f0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 65  nction returns e
27900 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
27910 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52     [SQLITE_ERROR
27920 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ], [SQLITE_BUSY]
27930 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
27940 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  USE]..*/.int sql
27950 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
27960 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
27970 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
27980 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
27990 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b 48 31  a result set {H1
279a0 33 37 37 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  3770} <S10700>.*
279b0 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 68 65  *.** Returns the
279c0 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65   number of value
279d0 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  s in the current
279e0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
279f0 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e  lt set..**.** IN
27a00 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
27a10 7b 48 31 33 37 37 31 7d 20 20 41 66 74 65 72 20  {H13771}  After 
27a20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
27a30 65 33 5f 73 74 65 70 28 53 29 5d 20 74 68 61 74  e3_step(S)] that
27a40 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
27a50 5f 52 4f 57 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  _ROW],.**       
27a60 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33      the [sqlite3
27a70 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20  _data_count(S)] 
27a80 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74  routine will ret
27a90 75 72 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c  urn the same val
27aa0 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ue.**           
27ab0 61 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  as the [sqlite3_
27ac0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d  column_count(S)]
27ad0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
27ae0 20 7b 48 31 33 37 37 32 7d 20 20 41 66 74 65 72   {H13772}  After
27af0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
27b00 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
27b10 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
27b20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  than.**         
27b30 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f    [SQLITE_ROW] o
27b40 72 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65  r before [sqlite
27b50 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 62  3_step(S)] has b
27b60 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68  een called on th
27b70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  e.**           [
27b80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27b90 6e 74 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  nt] for the firs
27ba0 74 20 74 69 6d 65 20 73 69 6e 63 65 20 69 74 20  t time since it 
27bb0 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  was.**          
27bc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
27bd0 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 6f 72  e | prepared] or
27be0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 20   [sqlite3_reset 
27bf0 7c 20 72 65 73 65 74 5d 2c 0a 2a 2a 20 20 20 20  | reset],.**    
27c00 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69         the [sqli
27c10 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53  te3_data_count(S
27c20 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
27c30 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20  ns zero..*/.int 
27c40 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
27c50 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
27c60 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
27c70 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
27c80 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 20  ental Datatypes 
27c90 7b 48 31 30 32 36 35 7d 20 3c 53 31 30 31 31 30  {H10265} <S10110
27ca0 3e 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59  ><S10120>.** KEY
27cb0 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
27cc0 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36  XT.**.** {H10266
27cd0 7d 20 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  } Every value in
27ce0 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
27cf0 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
27d00 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
27d10 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
27d20 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
27d30 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
27d40 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
27d50 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
27d60 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
27d70 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
27d80 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
27d90 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ul> {END}.**.** 
27da0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
27db0 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
27dc0 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
27dd0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
27de0 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
27df0 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
27e00 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
27e10 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
27e20 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
27e30 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
27e40 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
27e50 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
27e60 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
27e70 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
27e80 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
27e90 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
27ea0 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
27eb0 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
27ec0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
27ed0 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
27ee0 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
27ef0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
27f00 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
27f10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
27f20 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
27f30 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
27f40 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
27f50 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
27f60 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
27f70 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
27f80 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
27f90 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
27fa0 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
27fb0 20 46 72 6f 6d 20 41 20 51 75 65 72 79 20 7b 48   From A Query {H
27fc0 31 33 38 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a  13800} <S10700>.
27fd0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
27fe0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
27ff0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
28000 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
28010 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
28020 20 71 75 65 72 79 22 20 69 6e 74 65 72 66 61 63   query" interfac
28030 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e..**.** These r
28040 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
28050 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
28060 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
28070 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
28080 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  ** result row of
28090 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76   a query.  In ev
280a0 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
280b0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
280c0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
280d0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
280e0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
280f0 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
28100 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
28110 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
28120 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
28130 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
28140 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
28150 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
28160 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
28170 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
28180 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
28190 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
281a0 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
281b0 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
281c0 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63    The leftmost c
281d0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
281e0 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
281f0 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49  index 0..**.** I
28200 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
28210 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
28220 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
28230 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
28240 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
28250 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
28260 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
28270 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
28280 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
28290 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
282a0 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
282b0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
282c0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
282d0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
282e0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
282f0 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
28300 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
28310 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
28320 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
28330 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
28340 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
28350 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
28360 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
28370 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
28380 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
28390 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
283a0 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
283b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
283c0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
283d0 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
283e0 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
283f0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
28400 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
28410 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
28420 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
28430 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
28440 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
28450 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
28460 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
28470 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
28480 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
28490 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
284a0 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
284b0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
284c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
284d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
284e0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
284f0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
28500 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
28510 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
28520 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
28530 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
28540 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68  sult column.  Th
28550 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
28560 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
28570 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
28580 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
28590 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
285a0 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
285b0 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20   [SQLITE_NULL]. 
285c0 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   The value.** re
285d0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
285e0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
285f0 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
28600 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a  ul if no type.**
28610 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
28620 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65  e occurred as de
28630 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20  scribed below.  
28640 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e  After a type con
28650 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20  version,.** the 
28660 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
28670 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
28680 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66  _type() is undef
28690 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a  ined.  Future.**
286a0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
286b0 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74  ite may change t
286c0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
286d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
286e0 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  pe().** followin
286f0 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  g a type convers
28700 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ion..**.** If th
28710 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
28720 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
28730 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
28740 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28750 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
28760 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
28770 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
28780 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
28790 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  ..** If the resu
287a0 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
287b0 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
287c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
287d0 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
287e0 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
287f0 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
28800 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
28810 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74  f bytes..** If t
28820 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
28830 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
28840 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
28850 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
28860 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
28870 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
28880 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
28890 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
288a0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
288b0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
288c0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
288d0 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65  .** The value re
288e0 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20  turned does not 
288f0 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
28900 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74   terminator at t
28910 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
28920 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c   string.  For cl
28930 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
28940 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65   returned is the
28950 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
28960 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
28970 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
28980 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
28990 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72  .**.** Strings r
289a0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
289b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
289c0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
289d0 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
289e0 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
289f0 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
28a00 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e  zero terminated.
28a10 20 20 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20    The return.** 
28a20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
28a30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
28a40 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
28a50 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72  th BLOB is an ar
28a60 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74  bitrary.** point
28a70 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65  er, possibly eve
28a80 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
28a90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
28aa0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28ab0 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  16() routine is 
28ac0 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74  similar to sqlit
28ad0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
28ae0 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20  ).** but leaves 
28af0 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54  the result in UT
28b00 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62  F-16 in native b
28b10 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61  yte order instea
28b20 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54  d of UTF-8..** T
28b30 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
28b40 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64  or is not includ
28b50 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74  ed in this count
28b60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65  ..**.** The obje
28b70 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ct returned by [
28b80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
28b90 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a  alue()] is an.**
28ba0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
28bb0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
28bc0 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65  ect.  An unprote
28bd0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
28be0 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79  ue object.** may
28bf0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
28c00 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  th [sqlite3_bind
28c10 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
28c20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
28c30 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
28c40 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
28c50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
28c60 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
28c70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
28c80 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
28c90 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
28ca0 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
28cb0 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
28cc0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
28cd0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
28ce0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
28cf0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
28d00 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
28d10 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68  ytes()], then th
28d20 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
28d30 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
28d40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
28d50 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
28d60 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
28d70 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46   appropriate.  F
28d80 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
28d90 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
28da0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
28db0 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
28dc0 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
28dd0 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
28de0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
28df0 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
28e00 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
28e10 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
28e20 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54  utomatically.  T
28e30 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
28e40 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
28e50 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
28e60 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
28e70 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
28e80 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
28e90 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
28ea0 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
28eb0 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
28ec0 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
28ed0 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
28ee0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
28ef0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
28f00 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
28f10 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
28f20 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
28f30 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
28f40 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
28f50 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
28f60 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
28f70 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
28f80 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
28f90 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
28fa0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
28fb0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
28fc0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
28fd0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
28fe0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
28ff0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
29000 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
29010 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
29020 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
29030 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
29040 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
29050 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
29060 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
29070 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
29080 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
29090 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
290a0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
290b0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
290c0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
290d0 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65   float to intege
290e0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  r.** <tr><td>  F
290f0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
29100 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
29110 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
29120 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
29130 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
29140 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
29150 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e   Same as FLOAT->
29160 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
29170 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
29180 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73  NTEGER   <td> Us
29190 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
291a0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
291b0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
291c0 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  > Use atof().** 
291d0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
291e0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
291f0 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
29200 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
29210 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
29220 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74  R   <td> Convert
29230 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
29240 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e  e atoi().** <tr>
29250 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
29260 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
29270 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
29280 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28  T then use atof(
29290 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
292a0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
292b0 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
292c0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
292d0 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
292e0 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
292f0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
29300 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61  e table above ma
29310 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f  kes reference to
29320 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
29330 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74  ary functions at
29340 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66  oi().** and atof
29350 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73  ().  SQLite does
29360 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20   not really use 
29370 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
29380 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20    It has its.** 
29390 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69  own equivalent i
293a0 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73  nternal routines
293b0 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e  .  The atoi() an
293c0 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61  d atof() names a
293d0 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68  re.** used in th
293e0 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76  e table for brev
293f0 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20  ity and because 
29400 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61  they are familia
29410 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70  r to most.** C p
29420 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a  rogrammers..**.*
29430 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
29440 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
29450 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
29460 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
29470 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
29480 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29490 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
294a0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
294b0 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
294c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
294d0 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
294e0 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  ed..** Type conv
294f0 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
29500 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
29510 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
29520 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
29530 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
29540 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
29550 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
29560 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
29570 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
29580 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
29590 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
295a0 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
295b0 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
295c0 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
295d0 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
295e0 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
295f0 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
29600 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
29610 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
29620 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
29630 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
29640 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
29650 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
29660 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
29670 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
29680 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
29690 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
296a0 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
296b0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
296c0 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
296d0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
296e0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
296f0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
29700 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
29710 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
29720 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
29730 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
29740 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
29750 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65  /ul>.**.** Conve
29760 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
29770 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
29780 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
29790 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
297a0 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
297b0 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
297c0 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
297d0 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
297e0 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
297f0 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
29800 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69  rior pointer poi
29810 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65  nts to will have
29820 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
29830 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
29840 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
29850 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
29860 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
29870 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
29880 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
29890 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
298a0 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
298b0 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
298c0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
298d0 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20  *.** The safest 
298e0 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72  and easiest to r
298f0 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69  emember policy i
29900 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
29910 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
29920 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
29930 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
29940 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  * <ul>.**  <li>s
29950 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
29960 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
29970 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29980 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
29990 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
299a0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
299b0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
299c0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
299d0 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
299e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
299f0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
29a00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
29a10 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
29a20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
29a30 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
29a40 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
29a50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
29a60 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  ),.** sqlite3_co
29a70 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20  lumn_blob(), or 
29a80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
29a90 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
29aa0 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
29ab0 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65  t.** into the de
29ac0 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68  sired format, th
29ad0 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
29ae0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
29af0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
29b00 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
29b10 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  to find the size
29b20 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
29b30 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
29b40 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
29b50 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
29b60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29b70 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
29b80 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
29b90 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
29ba0 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78  , and do not mix
29bb0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
29bc0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
29bd0 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20  ).** with calls 
29be0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
29bf0 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a  n_bytes()..**.**
29c00 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   The pointers re
29c10 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64  turned are valid
29c20 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f   until a type co
29c30 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20  nversion occurs 
29c40 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20  as.** described 
29c50 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20  above, or until 
29c60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
29c70 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
29c80 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
29c90 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
29ca0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
29cb0 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
29cc0 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
29cd0 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
29ce0 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
29cf0 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
29d00 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
29d10 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
29d20 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
29d30 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
29d40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
29d50 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
29d60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
29d70 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  e()]..**.** If a
29d80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
29d90 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
29da0 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
29db0 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
29dc0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
29dd0 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
29de0 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
29df0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
29e00 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
29e10 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
29e20 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
29e30 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
29e40 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
29e50 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
29e60 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
29e70 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
29e80 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
29e90 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
29ea0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
29eb0 0a 2a 2a 20 7b 48 31 33 38 30 33 7d 20 54 68 65  .** {H13803} The
29ec0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
29ed0 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65  _blob(S,N)] inte
29ee0 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
29ef0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
29f00 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
29f10 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
29f20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
29f30 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  or.**          t
29f40 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
29f50 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
29f60 20 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e 20 72   BLOB and then r
29f70 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20  eturns a.**     
29f80 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20       pointer to 
29f90 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61  the converted va
29fa0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  lue..**.** {H138
29fb0 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  06} The [sqlite3
29fc0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c  _column_bytes(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 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
29ff0 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
2a000 62 79 74 65 73 20 69 6e 20 74 68 65 20 42 4c 4f  bytes in the BLO
2a010 42 20 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63  B or string (exc
2a020 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a  lusive of the.**
2a030 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
2a040 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65  erminator on the
2a050 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61   string) that wa
2a060 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
2a070 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f  e.**          mo
2a080 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2a090 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
2a0a0 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a  n_blob(S,N)] or.
2a0b0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2a0c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2a0d0 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  (S,N)]..**.** {H
2a0e0 31 33 38 30 39 7d 20 54 68 65 20 5b 73 71 6c 69  13809} The [sqli
2a0f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2a100 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
2a110 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ce returns the.*
2a120 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
2a130 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2a140 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73  e string (exclus
2a150 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ive of the.**   
2a160 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d         zero term
2a170 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74  inator on the st
2a180 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72  ring) that was r
2a190 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
2a1a0 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20  *          most 
2a1b0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2a1c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a1d0 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a  ext16(S,N)]..**.
2a1e0 2a 2a 20 7b 48 31 33 38 31 32 7d 20 54 68 65 20  ** {H13812} The 
2a1f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2a200 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74  double(S,N)] int
2a210 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2a220 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2a230 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
2a240 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
2a250 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2a260 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
2a270 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
2a280 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
2a290 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
2a2a0 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20   value and.**   
2a2b0 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61         returns a
2a2c0 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61   copy of that va
2a2d0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  lue..**.** {H138
2a2e0 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  15} The [sqlite3
2a2f0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29  _column_int(S,N)
2a300 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2a310 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2a320 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
2a330 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
2a340 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2a350 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20   set for the.** 
2a360 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
2a370 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2a380 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69  into a 64-bit si
2a390 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
2a3a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
2a3b0 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33  urns the lower 3
2a3c0 32 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69  2 bits of that i
2a3d0 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nteger..**.** {H
2a3e0 31 33 38 31 38 7d 20 54 68 65 20 5b 73 71 6c 69  13818} The [sqli
2a3f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
2a400 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
2a410 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2a420 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
2a430 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
2a440 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
2a450 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68  esult set for th
2a460 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2a470 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a480 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62  t] S into a 64-b
2a490 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2a4a0 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  r and.**        
2a4b0 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79    returns a copy
2a4c0 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72   of that integer
2a4d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 31 7d  ..**.** {H13821}
2a4e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2a4f0 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20  lumn_text(S,N)] 
2a500 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2a510 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2a520 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
2a530 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
2a540 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2a550 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  et for.**       
2a560 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64     the [prepared
2a570 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
2a580 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2a590 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20  ated UTF-8.**   
2a5a0 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
2a5b0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
2a5c0 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
2a5d0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32  ng..**.** {H1382
2a5e0 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
2a5f0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c  column_text16(S,
2a600 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
2a610 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2a620 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
2a630 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
2a640 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2a650 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a  lt set for the.*
2a660 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2a670 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a680 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65  S into a zero-te
2a690 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a  rminated 2-byte.
2a6a0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69 67  **          alig
2a6b0 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76  ned UTF-16 nativ
2a6c0 65 20 62 79 74 65 20 6f 72 64 65 72 20 73 74 72  e byte order str
2a6d0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2a6e0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 6f  **          a po
2a6f0 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
2a700 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ring..**.** {H13
2a710 38 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  827} The [sqlite
2a720 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c  3_column_type(S,
2a730 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
2a740 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
2a750 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45    one of [SQLITE
2a760 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NULL], [SQLITE_
2a770 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54  INTEGER], [SQLIT
2a780 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20  E_FLOAT],.**    
2a790 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45        [SQLITE_TE
2a7a0 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  XT], or [SQLITE_
2a7b0 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72  BLOB] as appropr
2a7c0 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  iate for.**     
2a7d0 20 20 20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c       the Nth col
2a7e0 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
2a7f0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2a800 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20  sult set for.** 
2a810 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72           the [pr
2a820 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a830 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  ] S..**.** {H138
2a840 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  30} The [sqlite3
2a850 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c  _column_value(S,
2a860 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
2a870 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20  turns a.**      
2a880 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61      pointer to a
2a890 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
2a8a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2a8b0 6a 65 63 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ject for the.** 
2a8c0 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
2a8d0 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
2a8e0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2a8f0 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20  sult set for.** 
2a900 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72           the [pr
2a910 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a920 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ] S..*/.const vo
2a930 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2a940 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
2a950 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2a960 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2a970 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
2a980 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2a990 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2a9a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2a9b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a9c0 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
2a9d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a9e0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
2a9f0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2aa00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2aa10 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
2aa20 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2aa30 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
2aa40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2aa50 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
2aa60 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
2aa70 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
2aa80 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2aa90 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
2aaa0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2aab0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2aac0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2aad0 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
2aae0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2aaf0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2ab00 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
2ab10 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2ab20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
2ab30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2ab40 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
2ab50 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
2ab60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2ab70 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
2ab80 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
2ab90 63 74 20 7b 48 31 33 33 30 30 7d 20 3c 53 37 30  ct {H13300} <S70
2aba0 33 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a  300><S30100>.**.
2abb0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66  ** The sqlite3_f
2abc0 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
2abd0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2abe0 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
2abf0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2ac00 2a 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65  * If the stateme
2ac10 6e 74 20 77 61 73 20 65 78 65 63 75 74 65 64 20  nt was executed 
2ac20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f 72 20  successfully or 
2ac30 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61 74 20  not executed at 
2ac40 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  all, then.** SQL
2ac50 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e  ITE_OK is return
2ac60 65 64 2e 20 49 66 20 65 78 65 63 75 74 69 6f 6e  ed. If execution
2ac70 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
2ac80 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e  t failed then an
2ac90 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
2aca0 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
2acb0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
2acc0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  urned..**.** Thi
2acd0 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
2ace0 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
2acf0 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20  oint during the 
2ad00 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
2ad10 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2ad20 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68  atement].  If th
2ad30 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  e virtual machin
2ad40 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d  e has not.** com
2ad50 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
2ad60 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   when this routi
2ad70 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  ne is called, th
2ad80 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e  at is like.** en
2ad90 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72  countering an er
2ada0 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74  ror or an [sqlit
2adb0 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69  e3_interrupt | i
2adc0 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e  nterrupt]..** In
2add0 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73  complete updates
2ade0 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62   may be rolled b
2adf0 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74  ack and transact
2ae00 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a  ions canceled,.*
2ae10 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  * depending on t
2ae20 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  he circumstances
2ae30 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72  , and the.** [er
2ae40 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e  ror code] return
2ae50 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49  ed will be [SQLI
2ae60 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a  TE_ABORT]..**.**
2ae70 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2ae80 2a 2a 20 7b 48 31 31 33 30 32 7d 20 54 68 65 20  ** {H11302} The 
2ae90 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2aea0 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(S)] interface 
2aeb0 64 65 73 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20  destroys the.** 
2aec0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
2aed0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2aee0 61 6e 64 20 72 65 6c 65 61 73 65 73 20 61 6c 6c  and releases all
2aef0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d  .**          mem
2af00 6f 72 79 20 61 6e 64 20 66 69 6c 65 20 72 65 73  ory and file res
2af10 6f 75 72 63 65 73 20 68 65 6c 64 20 62 79 20 74  ources held by t
2af20 68 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  hat object..**.*
2af30 2a 20 7b 48 31 31 33 30 34 7d 20 49 66 20 74 68  * {H11304} If th
2af40 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2af50 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2af60 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
2af70 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
2af80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2af90 20 53 20 72 65 74 75 72 6e 65 64 20 61 6e 20 65   S returned an e
2afa0 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20  rror,.**        
2afb0 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f    then [sqlite3_
2afc0 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72 65 74  finalize(S)] ret
2afd0 75 72 6e 73 20 74 68 61 74 20 73 61 6d 65 20 65  urns that same e
2afe0 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rror..*/.int sql
2aff0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
2b000 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2b010 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2b020 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
2b030 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2b040 4f 62 6a 65 63 74 20 7b 48 31 33 33 33 30 7d 20  Object {H13330} 
2b050 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S70300>.**.** T
2b060 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
2b070 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
2b080 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
2b090 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b0a0 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
2b0b0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2b0c0 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
2b0d0 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
2b0e0 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73  ed..** Any SQL s
2b0f0 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c  tatement variabl
2b100 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75  es that had valu
2b110 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d  es bound to them
2b120 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
2b130 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2b140 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
2b150 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20  *() API] retain 
2b160 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a  their values..**
2b170 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   Use [sqlite3_cl
2b180 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20  ear_bindings()] 
2b190 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e  to reset the bin
2b1a0 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  dings..**.** {H1
2b1b0 31 33 33 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  1332} The [sqlit
2b1c0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
2b1d0 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
2b1e0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2b1f0 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20  ement] S.**     
2b200 20 20 20 20 20 62 61 63 6b 20 74 6f 20 74 68 65       back to the
2b210 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
2b220 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
2b230 20 7b 48 31 31 33 33 34 7d 20 49 66 20 74 68 65   {H11334} If the
2b240 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2b250 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2b260 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
2b270 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2b280 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2b290 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
2b2a0 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
2b2b0 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20  TE_DONE],.**    
2b2c0 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71 6c        or if [sql
2b2d0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
2b2e0 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
2b2f0 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
2b300 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
2b310 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
2b320 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
2b330 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
2b340 7b 48 31 31 33 33 36 7d 20 49 66 20 74 68 65 20  {H11336} If the 
2b350 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2b360 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2b370 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
2b380 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
2b390 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2b3a0 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
2b3b0 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  ror, then.**    
2b3c0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
2b3d0 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
2b3e0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
2b3f0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
2b400 0a 2a 2a 20 7b 48 31 31 33 33 38 7d 20 54 68 65  .** {H11338} The
2b410 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2b420 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
2b430 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
2b440 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20  e values.**     
2b450 20 20 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c       of any [sql
2b460 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
2b470 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
2b480 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b490 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
2b4a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
2b4b0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2b4c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b4d0 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
2b4e0 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
2b4f0 69 6f 6e 73 20 7b 48 31 36 31 30 30 7d 20 3c 53  ions {H16100} <S
2b500 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  20200>.** KEYWOR
2b510 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
2b520 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
2b530 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2b540 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2b550 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
2b560 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2b570 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2b580 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2b590 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77  }.**.** These tw
2b5a0 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  o functions (col
2b5b0 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
2b5c0 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
2b5d0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
2b5e0 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
2b5f0 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
2b600 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
2b610 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
2b620 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
2b630 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
2b640 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
2b650 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
2b660 79 20 64 69 66 66 65 72 65 6e 63 65 20 62 65 74  y difference bet
2b670 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20  ween the.** two 
2b680 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  is that the seco
2b690 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  nd parameter, th
2b6a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73  e name of the (s
2b6b0 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20  calar) function 
2b6c0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c  or.** aggregate,
2b6d0 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55   is encoded in U
2b6e0 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33  TF-8 for sqlite3
2b6f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2b700 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a  () and UTF-16.**
2b710 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
2b720 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2b730 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
2b740 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
2b750 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2b760 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
2b770 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
2b780 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
2b790 64 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67  dded.  If a sing
2b7a0 6c 65 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20  le program uses 
2b7b0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61  more than one da
2b7c0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
2b7d0 74 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c  tion internally,
2b7e0 20 74 68 65 6e 20 53 51 4c 20 66 75 6e 63 74 69   then SQL functi
2b7f0 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  ons must be adde
2b800 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74  d individually t
2b810 6f 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62 61  o.** each databa
2b820 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a  se connection..*
2b830 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
2b840 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2b850 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
2b860 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2b870 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
2b880 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20 6c 65  defined.  The le
2b890 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
2b8a0 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
2b8b0 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73  55 bytes, exclus
2b8c0 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65  ive of.** the ze
2b8d0 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
2b8e0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
2b8f0 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  me length limit 
2b900 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74  is in bytes, not
2b910 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20  .** characters. 
2b920 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
2b930 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
2b940 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
2b950 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
2b960 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45  ult in [SQLITE_E
2b970 52 52 4f 52 5d 20 62 65 69 6e 67 20 72 65 74 75  RROR] being retu
2b980 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
2b990 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2b9a0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
2b9b0 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
2b9c0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2b9d0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
2b9e0 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20   takes. If this 
2b9f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67  parameter is neg
2ba00 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
2ba10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2ba20 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
2ba30 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
2ba40 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a   of arguments..*
2ba50 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  *.** The fourth 
2ba60 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
2ba70 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
2ba80 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
2ba90 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
2baa0 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
2bab0 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
2bac0 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
2bad0 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66  ters.  Any SQL f
2bae0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2baf0 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  tation should be
2bb00 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
2bb10 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38   work with UTF-8
2bb20 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55  , UTF-16le, or U
2bb30 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f  TF-16be.  But so
2bb40 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  me implementatio
2bb50 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72  ns may be.** mor
2bb60 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68  e efficient with
2bb70 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68   one encoding th
2bb80 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20  an another.  It 
2bb90 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a  is allowed to.**
2bba0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
2bbb0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2bbc0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
2bbd0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2bbe0 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d   multiple.** tim
2bbf0 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  es with the same
2bc00 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69   function but wi
2bc10 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c  th different val
2bc20 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e  ues of eTextRep.
2bc30 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c  .** When multipl
2bc40 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2bc50 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
2bc60 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
2bc70 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
2bc80 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
2bc90 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
2bca0 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
2bcb0 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
2bcc0 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65  ion..** If there
2bcd0 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c   is only a singl
2bce0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2bcf0 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20   which does not 
2bd00 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a  care what text.*
2bd10 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  * encoding is us
2bd20 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75  ed, then the fou
2bd30 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rth argument sho
2bd40 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  uld be [SQLITE_A
2bd50 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  NY]..**.** The f
2bd60 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
2bd70 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
2bd80 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
2bd90 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
2bda0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
2bdb0 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
2bdc0 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
2bdd0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
2bde0 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a  er_data()]..**.*
2bdf0 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65  * The seventh, e
2be00 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20  ighth and ninth 
2be10 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
2be20 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
2be30 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
2be40 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
2be50 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
2be60 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
2be70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2be80 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 41 20  ** aggregate. A 
2be90 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
2bea0 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
2beb0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2bec0 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
2bed0 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55  allback only, NU
2bee0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75  LL pointers shou
2bef0 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73 20  ld be passed as 
2bf00 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46  the xStep and xF
2bf10 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65  inal.** paramete
2bf20 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65  rs. An aggregate
2bf30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
2bf40 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
2bf50 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65  entation of xSte
2bf60 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
2bf70 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20  and NULL should 
2bf80 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46  be passed for xF
2bf90 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61  unc. To delete a
2bfa0 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51  n existing.** SQ
2bfb0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
2bfc0 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
2bfd0 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  LL for all three
2bfe0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
2bff0 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  cks..**.** It is
2c000 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
2c010 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
2c020 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2c030 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
2c040 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
2c050 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
2c060 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
2c070 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
2c080 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
2c090 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65   differing prefe
2c0a0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
2c0b0 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ngs.  SQLite wil
2c0c0 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
2c0d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74  lementation most
2c0e0 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
2c0f0 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
2c100 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
2c110 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ction is used..*
2c120 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2c130 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 33 7d 20  .**.** {H16103} 
2c140 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
2c150 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2c160 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 68 61  ] interface beha
2c170 76 65 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20  ves exactly.**  
2c180 20 20 20 20 20 20 20 20 6c 69 6b 65 20 5b 73 71          like [sq
2c190 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2c1a0 63 74 69 6f 6e 28 29 5d 20 69 6e 20 65 76 65 72  ction()] in ever
2c1b0 79 20 77 61 79 20 65 78 63 65 70 74 20 74 68 61  y way except tha
2c1c0 74 20 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  t it.**         
2c1d0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
2c1e0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 20 61 72  zFunctionName ar
2c1f0 67 75 6d 65 6e 74 20 61 73 20 7a 65 72 6f 2d 74  gument as zero-t
2c200 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36  erminated UTF-16
2c210 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 74  .**          nat
2c220 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
2c230 6e 73 74 65 61 64 20 6f 66 20 61 73 20 7a 65 72  nstead of as zer
2c240 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
2c250 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30  -8..**.** {H1610
2c260 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  6} A successful 
2c270 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a  invocation of.**
2c280 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73            the [s
2c290 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2c2a0 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e  nction(D,X,N,E,.
2c2b0 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ..)] interface r
2c2c0 65 67 69 73 74 65 72 73 0a 2a 2a 20 20 20 20 20  egisters.**     
2c2d0 20 20 20 20 20 6f 72 20 72 65 70 6c 61 63 65 73       or replaces
2c2e0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2c2f0 6f 6e 73 20 69 6e 20 74 68 65 20 5b 64 61 74 61  ons in the [data
2c300 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2c310 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75   D.**          u
2c320 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
2c330 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2c340 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 4e  n named X with N
2c350 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20   parameters.**  
2c360 20 20 20 20 20 20 20 20 61 6e 64 20 68 61 76 69          and havi
2c370 6e 67 20 61 20 70 72 65 66 65 72 72 65 64 20 74  ng a preferred t
2c380 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  ext encoding of 
2c390 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 39  E..**.** {H16109
2c3a0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
2c3b0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2c3c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2c3d0 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
2c3e0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  ].**          re
2c3f0 70 6c 61 63 65 73 20 74 68 65 20 50 2c 20 46 2c  places the P, F,
2c400 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65 73   S, and L values
2c410 20 66 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72 20   from any prior 
2c420 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20  calls with.**   
2c430 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20         the same 
2c440 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20 76  D, X, N, and E v
2c450 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  alues..**.** {H1
2c460 36 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  6112} The [sqlit
2c470 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2c480 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74  on(D,X,...)] int
2c490 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
2c4a0 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  h.**          a 
2c4b0 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b  return code of [
2c4c0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
2c4d0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2c4e0 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20 20  n name X is.**  
2c4f0 20 20 20 20 20 20 20 20 6c 6f 6e 67 65 72 20 74          longer t
2c500 68 61 6e 20 32 35 35 20 62 79 74 65 73 20 65 78  han 255 bytes ex
2c510 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
2c520 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
2c530 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 38 7d 20 45  **.** {H16118} E
2c540 69 74 68 65 72 20 46 20 6d 75 73 74 20 62 65 20  ither F must be 
2c550 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c  NULL and S and L
2c560 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72   are non-NULL or
2c570 20 65 6c 73 65 20 46 0a 2a 2a 20 20 20 20 20 20   else F.**      
2c580 20 20 20 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20      is non-NULL 
2c590 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20  and S and L are 
2c5a0 4e 55 4c 4c 2c 20 6f 74 68 65 72 77 69 73 65 0a  NULL, otherwise.
2c5b0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2c5c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2c5d0 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  tion(D,X,N,E,P,F
2c5e0 2c 53 2c 4c 29 5d 20 72 65 74 75 72 6e 73 20 5b  ,S,L)] returns [
2c5f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a  SQLITE_ERROR]..*
2c600 2a 0a 2a 2a 20 7b 48 31 36 31 32 31 7d 20 54 68  *.** {H16121} Th
2c610 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2c620 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e  e_function(D,...
2c630 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  )] interface fai
2c640 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20  ls with an.**   
2c650 20 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f 64         error cod
2c660 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42 55 53  e of [SQLITE_BUS
2c670 59 5d 20 69 66 20 74 68 65 72 65 20 65 78 69 73  Y] if there exis
2c680 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  t [prepared stat
2c690 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20 20 20  ements].**      
2c6a0 20 20 20 20 61 73 73 6f 63 69 61 74 65 64 20 77      associated w
2c6b0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
2c6c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e  e connection] D.
2c6d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 34 7d 20  .**.** {H16124} 
2c6e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
2c6f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2c700 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ,N,...)] interfa
2c710 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  ce fails with an
2c720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 72  .**          err
2c730 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  or code of [SQLI
2c740 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 70 61 72  TE_ERROR] if par
2c750 61 6d 65 74 65 72 20 4e 20 28 73 70 65 63 69 66  ameter N (specif
2c760 79 69 6e 67 20 74 68 65 20 6e 75 6d 62 65 72 0a  ying the number.
2c770 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61  **          of a
2c780 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
2c790 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  SQL function bei
2c7a0 6e 67 20 72 65 67 69 73 74 65 72 65 64 29 20 69  ng registered) i
2c7b0 73 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 20  s less.**       
2c7c0 20 20 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72     than -1 or gr
2c7d0 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 2e 0a  eater than 127..
2c7e0 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 37 7d 20 57  **.** {H16127} W
2c7f0 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67  hen N is non-neg
2c800 61 74 69 76 65 2c 20 74 68 65 20 5b 73 71 6c 69  ative, the [sqli
2c810 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2c820 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a  ion(D,X,N,...)].
2c830 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
2c840 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61 6c  rface causes cal
2c850 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76  lbacks to be inv
2c860 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c  oked for the SQL
2c870 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20   function.**    
2c880 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 68        named X wh
2c890 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  en the number of
2c8a0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
2c8b0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
2c8c0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78  s.**          ex
2c8d0 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b  actly N..**.** {
2c8e0 48 31 36 31 33 30 7d 20 57 68 65 6e 20 4e 20 69  H16130} When N i
2c8f0 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c 69 74  s -1, the [sqlit
2c900 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2c910 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a  on(D,X,N,...)].*
2c920 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
2c930 66 61 63 65 20 63 61 75 73 65 73 20 63 61 6c 6c  face causes call
2c940 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f  backs to be invo
2c950 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c 20  ked for the SQL 
2c960 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  function.**     
2c970 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77 69 74       named X wit
2c980 68 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  h any number of 
2c990 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
2c9a0 20 7b 48 31 36 31 33 33 7d 20 57 68 65 6e 20 63   {H16133} When c
2c9b0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2c9c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c9d0 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20  (D,X,N,...)].** 
2c9e0 20 20 20 20 20 20 20 20 20 73 70 65 63 69 66 79           specify
2c9f0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
2ca00 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
2ca10 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58   same function X
2ca20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
2ca30 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d   when one implem
2ca40 65 6e 74 61 74 69 6f 6e 20 68 61 73 20 4e 3e 3d  entation has N>=
2ca50 30 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  0 and the other 
2ca60 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20  has N=(-1).**   
2ca70 20 20 20 20 20 20 20 74 68 65 20 69 6d 70 6c 65         the imple
2ca80 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
2ca90 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 69 73 20 70   non-zero N is p
2caa0 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  referred..**.** 
2cab0 7b 48 31 36 31 33 36 7d 20 57 68 65 6e 20 63 61  {H16136} When ca
2cac0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2cad0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2cae0 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a  D,X,N,E,...)].**
2caf0 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69 66            specif
2cb00 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  y multiple imple
2cb10 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
2cb20 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2cb30 58 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  X with.**       
2cb40 20 20 20 74 68 65 20 73 61 6d 65 20 6e 75 6d 62     the same numb
2cb50 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2cb60 4e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  N but with diffe
2cb70 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  rent.**         
2cb80 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74 68   encodings E, th
2cb90 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  en the implement
2cba0 61 74 69 6f 6e 20 77 68 65 72 65 20 45 20 6d 61  ation where E ma
2cbb0 74 63 68 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  tches the.**    
2cbc0 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20 65        database e
2cbd0 6e 63 6f 64 69 6e 67 20 69 73 20 70 72 65 66 65  ncoding is prefe
2cbe0 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  rred..**.** {H16
2cbf0 31 33 39 7d 20 46 6f 72 20 61 6e 20 61 67 67 72  139} For an aggr
2cc00 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2cc10 6f 6e 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  on created using
2cc20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2cc30 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2cc40 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
2cc50 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e 61  0,S,L)] the fina
2cc60 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  lizer.**        
2cc70 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20 77 69 6c    function L wil
2cc80 6c 20 61 6c 77 61 79 73 20 62 65 20 69 6e 76 6f  l always be invo
2cc90 6b 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  ked exactly once
2cca0 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   if the.**      
2ccb0 20 20 20 20 73 74 65 70 20 66 75 6e 63 74 69 6f      step functio
2ccc0 6e 20 53 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  n S is called on
2ccd0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
2cce0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 34 32 7d 20  .**.** {H16142} 
2ccf0 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f  When SQLite invo
2cd00 6b 65 73 20 65 69 74 68 65 72 20 74 68 65 20 78  kes either the x
2cd10 46 75 6e 63 20 6f 72 20 78 53 74 65 70 20 66 75  Func or xStep fu
2cd20 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20  nction of.**    
2cd30 20 20 20 20 20 20 61 6e 20 61 70 70 6c 69 63 61        an applica
2cd40 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2cd50 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
2cd60 72 65 67 61 74 65 20 63 72 65 61 74 65 64 0a 2a  regate created.*
2cd70 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 5b 73  *          by [s
2cd80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2cd90 6e 63 74 69 6f 6e 28 29 5d 20 6f 72 20 5b 73 71  nction()] or [sq
2cda0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2cdb0 63 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20  ction16()],.**  
2cdc0 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65          then the
2cdd0 20 61 72 72 61 79 20 6f 66 20 5b 73 71 6c 69 74   array of [sqlit
2cde0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2cdf0 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  s passed as the.
2ce00 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 69 72  **          thir
2ce10 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
2ce20 61 6c 77 61 79 73 20 5b 70 72 6f 74 65 63 74 65  always [protecte
2ce30 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2ce40 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74   objects..*/.int
2ce50 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2ce60 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
2ce70 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
2ce80 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
2ce90 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
2cea0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2ceb0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
2cec0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
2ced0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2cee0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2cef0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2cf00 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
2cf10 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2cf20 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2cf30 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
2cf40 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2cf50 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2cf60 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2cf70 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
2cf80 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
2cf90 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2cfa0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2cfb0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2cfc0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2cfd0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2cfe0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2cff0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2d000 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2d010 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2d020 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2d030 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2d040 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2d050 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a  context*).);../*
2d060 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
2d070 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b 48 31  xt Encodings {H1
2d080 30 32 36 37 7d 20 3c 53 35 30 32 30 30 3e 20 3c  0267} <S50200> <
2d090 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  H16100>.**.** Th
2d0a0 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
2d0b0 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
2d0c0 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
2d0d0 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
2d0e0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
2d0f0 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
2d100 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
2d110 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
2d120 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
2d130 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
2d140 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
2d150 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
2d160 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
2d170 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
2d180 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
2d190 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2d1a0 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
2d1b0 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
2d1c0 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69      5    /* sqli
2d1d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2d1e0 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  ion only */.#def
2d1f0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2d200 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
2d210 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
2d220 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
2d230 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
2d240 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
2d250 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
2d260 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
2d270 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
2d280 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
2d290 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
2d2a0 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
2d2b0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
2d2c0 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
2d2d0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2d2e0 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
2d2f0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
2d300 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
2d310 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
2d320 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
2d330 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
2d340 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65  ions.  To help e
2d350 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20  ncourage people 
2d360 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e  to avoid.** usin
2d370 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  g these function
2d380 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f  s, we are not go
2d390 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20  ing to tell you 
2d3a0 77 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  want they do..*/
2d3b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67  .int sqlite3_agg
2d3c0 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
2d3d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2d3e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
2d3f0 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
2d400 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
2d410 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
2d420 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
2d430 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
2d440 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f  .int sqlite3_glo
2d450 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64  bal_recover(void
2d460 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2d470 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76  thread_cleanup(v
2d480 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
2d490 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
2d4a0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2d4b0 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
2d4c0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
2d4d0 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t64);../*.** CAP
2d4e0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67  I3REF: Obtaining
2d4f0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61   SQL Function Pa
2d500 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 20 7b  rameter Values {
2d510 48 31 35 31 30 30 7d 20 3c 53 32 30 32 30 30 3e  H15100} <S20200>
2d520 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
2d530 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
2d540 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
2d550 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
2d560 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
2d570 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
2d580 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
2d590 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
2d5a0 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
2d5b0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
2d5c0 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a   aggregate..**.*
2d5d0 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
2d5e0 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
2d5f0 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
2d600 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
2d610 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
2d620 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2d630 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
2d640 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2d650 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
2d660 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
2d670 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
2d680 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
2d690 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
2d6a0 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61 72 61  .** The 4th para
2d6b0 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
2d6c0 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
2d6d0 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
2d6e0 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
2d6f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2d700 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
2d710 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
2d720 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
2d730 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
2d740 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
2d750 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
2d760 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
2d770 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
2d780 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
2d790 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2d7a0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
2d7b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
2d7c0 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
2d7d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d7e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2d7f0 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
2d800 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
2d810 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
2d820 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d830 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
2d840 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
2d850 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
2d860 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2d870 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
2d880 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
2d890 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
2d8a0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
2d8b0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
2d8c0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2d8d0 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70  take a single [p
2d8e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d8f0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
2d900 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  * pointer instea
2d910 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  d of a [sqlite3_
2d920 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61  stmt*] pointer a
2d930 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  nd an integer co
2d940 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  lumn number..**.
2d950 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
2d960 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e  alue_text16() in
2d970 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73  terface extracts
2d980 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2d990 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76  .** in the nativ
2d9a0 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20  e byte-order of 
2d9b0 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65  the host machine
2d9c0 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
2d9d0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
2d9e0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
2d9f0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
2da00 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
2da10 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72  tract UTF-16 str
2da20 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
2da30 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
2da40 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
2da50 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
2da60 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
2da70 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66  ic_type() interf
2da80 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
2da90 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63  apply.** numeric
2daa0 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65   affinity to the
2dab0 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65   value.  This me
2dac0 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65  ans that an atte
2dad0 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74  mpt is.** made t
2dae0 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
2daf0 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  lue to an intege
2db00 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f  r or floating po
2db10 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68  int.  If.** such
2db20 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73   a conversion is
2db30 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75   possible withou
2db40 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d  t loss of inform
2db50 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a  ation (in other.
2db60 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65  ** words, if the
2db70 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69   value is a stri
2db80 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69  ng that looks li
2db90 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20  ke a number).** 
2dba0 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73  then the convers
2dbb0 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
2dbc0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20  .  Otherwise no 
2dbd0 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
2dbe0 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  s..** The [SQLIT
2dbf0 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
2dc00 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76  type] after conv
2dc10 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e  ersion is return
2dc20 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65  ed..**.** Please
2dc30 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20   pay particular 
2dc40 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65  attention to the
2dc50 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70   fact that the p
2dc60 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a  ointer returned.
2dc70 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
2dc80 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
2dc90 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2dca0 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
2dcb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2dcc0 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
2dcd0 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
2dce0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
2dcf0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
2dd00 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
2dd10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2dd20 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
2dd30 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2dd40 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
2dd50 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
2dd60 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2dd70 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
2dd80 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
2dd90 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
2dda0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2ddb0 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
2ddc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2ddd0 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  e*] parameters..
2dde0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2ddf0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 33 7d  :.**.** {H15103}
2de00 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2de10 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 69 6e 74  lue_blob(V)] int
2de20 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2de30 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2de40 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2de50 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2de60 20 56 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61   V into a BLOB a
2de70 6e 64 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  nd then.**      
2de80 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 70 6f      returns a po
2de90 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e  inter to the con
2dea0 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a  verted value..**
2deb0 0a 2a 2a 20 7b 48 31 35 31 30 36 7d 20 54 68 65  .** {H15106} The
2dec0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2ded0 62 79 74 65 73 28 56 29 5d 20 69 6e 74 65 72 66  bytes(V)] interf
2dee0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ace returns the.
2def0 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62  **          numb
2df00 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2df10 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
2df20 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20  g (exclusive of 
2df30 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2df40 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2df50 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74  on the string) t
2df60 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
2df70 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   by the.**      
2df80 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20      most recent 
2df90 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2dfa0 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20  _value_blob(V)] 
2dfb0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
2dfc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2dfd0 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  xt(V)]..**.** {H
2dfe0 31 35 31 30 39 7d 20 54 68 65 20 5b 73 71 6c 69  15109} The [sqli
2dff0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
2e000 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  6(V)] interface 
2e010 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20  returns the.**  
2e020 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f          number o
2e030 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  f bytes in the s
2e040 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65  tring (exclusive
2e050 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
2e060 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61      zero termina
2e070 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e  tor on the strin
2e080 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75  g) that was retu
2e090 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20  rned by the.**  
2e0a0 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63          most rec
2e0b0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2e0c0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2e0d0 36 28 56 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  6(V)],.**       
2e0e0 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75     [sqlite3_valu
2e0f0 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d 2c 20  e_text16be(V)], 
2e100 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
2e110 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d 2e 0a  e_text16le(V)]..
2e120 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 32 7d 20 54  **.** {H15112} T
2e130 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2e140 65 5f 64 6f 75 62 6c 65 28 56 29 5d 20 69 6e 74  e_double(V)] int
2e150 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2e160 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2e170 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2e180 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2e190 20 56 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69   V into a floati
2e1a0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61  ng point value a
2e1b0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
2e1c0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
2e1d0 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a   that value..**.
2e1e0 2a 2a 20 7b 48 31 35 31 31 35 7d 20 54 68 65 20  ** {H15115} The 
2e1f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
2e200 6e 74 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65  nt(V)] interface
2e210 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2e220 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65            [prote
2e230 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2e240 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74  ue] object V int
2e250 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65  o a 64-bit signe
2e260 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a  d integer and.**
2e270 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
2e280 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62  s the lower 32 b
2e290 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65  its of that inte
2e2a0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  ger..**.** {H151
2e2b0 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  18} The [sqlite3
2e2c0 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 56 29 5d  _value_int64(V)]
2e2d0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2e2e0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2e2f0 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2e300 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2e310 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 36 34  ject V into a 64
2e320 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2e330 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ger and.**      
2e340 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f      returns a co
2e350 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67  py of that integ
2e360 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32  er..**.** {H1512
2e370 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
2e380 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 20 69  value_text(V)] i
2e390 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2e3a0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2e3b0 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2e3c0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2e3d0 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f  ct V into a zero
2e3e0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
2e3f0 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  8.**          st
2e400 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2e410 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2e420 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
2e430 20 7b 48 31 35 31 32 34 7d 20 54 68 65 20 5b 73   {H15124} The [s
2e440 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2e450 74 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63  t16(V)] interfac
2e460 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
2e470 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
2e480 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e490 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
2e4a0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2e4b0 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20  ated 2-byte.**  
2e4c0 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20          aligned 
2e4d0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
2e4e0 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20 20 20  te order.**     
2e4f0 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
2e500 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2e510 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
2e520 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 37 7d  ..**.** {H15127}
2e530 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2e540 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d  lue_text16be(V)]
2e550 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2e560 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2e570 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2e580 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2e590 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65  ject V into a ze
2e5a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d  ro-terminated 2-
2e5b0 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  byte.**         
2e5c0 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20   aligned UTF-16 
2e5d0 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20  big-endian.**   
2e5e0 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
2e5f0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
2e600 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
2e610 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33  ng..**.** {H1513
2e620 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  0} The [sqlite3_
2e630 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56  value_text16le(V
2e640 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2e650 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2e660 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
2e670 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2e680 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
2e690 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2e6a0 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20  2-byte.**       
2e6b0 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31     aligned UTF-1
2e6c0 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a  6 little-endian.
2e6d0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
2e6e0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
2e6f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
2e700 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
2e710 48 31 35 31 33 33 7d 20 54 68 65 20 5b 73 71 6c  H15133} The [sql
2e720 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
2e730 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  V)] interface re
2e740 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
2e750 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45    one of [SQLITE
2e760 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NULL], [SQLITE_
2e770 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54  INTEGER], [SQLIT
2e780 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20  E_FLOAT],.**    
2e790 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45        [SQLITE_TE
2e7a0 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  XT], or [SQLITE_
2e7b0 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72  BLOB] as appropr
2e7c0 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  iate for.**     
2e7d0 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
2e7e0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2e7f0 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 36  V..**.** {H15136
2e800 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2e810 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
2e820 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(V)] interface 
2e830 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 20 20 20 20  converts.**     
2e840 20 20 20 20 20 74 68 65 20 5b 70 72 6f 74 65 63       the [protec
2e850 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2e860 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
2e870 20 65 69 74 68 65 72 20 61 6e 20 69 6e 74 65 67   either an integ
2e880 65 72 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  er or.**        
2e890 20 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69    a floating poi
2e8a0 6e 74 20 76 61 6c 75 65 20 69 66 20 69 74 20 63  nt value if it c
2e8b0 61 6e 20 64 6f 20 73 6f 20 77 69 74 68 6f 75 74  an do so without
2e8c0 20 6c 6f 73 73 20 6f 66 0a 2a 2a 20 20 20 20 20   loss of.**     
2e8d0 20 20 20 20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e       information
2e8e0 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 6f 6e  , and returns on
2e8f0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  e of [SQLITE_NUL
2e900 4c 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  L],.**          
2e910 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
2e920 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  , [SQLITE_FLOAT]
2e930 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
2e940 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
2e950 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73  [SQLITE_BLOB] as
2e960 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
2e970 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2e980 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2e990 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2e9a0 74 20 56 20 61 66 74 65 72 20 74 68 65 20 63 6f  t V after the co
2e9b0 6e 76 65 72 73 69 6f 6e 20 61 74 74 65 6d 70 74  nversion attempt
2e9c0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ..*/.const void 
2e9d0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  *sqlite3_value_b
2e9e0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  lob(sqlite3_valu
2e9f0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2ea00 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c  _value_bytes(sql
2ea10 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2ea20 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2ea30 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
2ea40 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20  value*);.double 
2ea50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f  sqlite3_value_do
2ea60 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  uble(sqlite3_val
2ea70 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2ea80 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69  3_value_int(sqli
2ea90 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c  te3_value*);.sql
2eaa0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
2eab0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73  e3_value_int64(s
2eac0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2ead0 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
2eae0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  har *sqlite3_val
2eaf0 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  ue_text(sqlite3_
2eb00 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
2eb10 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2eb20 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  ue_text16(sqlite
2eb30 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
2eb40 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
2eb50 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71  alue_text16le(sq
2eb60 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
2eb70 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2eb80 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
2eb90 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2eba0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
2ebb0 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65  alue_type(sqlite
2ebc0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2ebd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
2ebe0 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65  eric_type(sqlite
2ebf0 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
2ec00 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
2ec10 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e  in Aggregate Fun
2ec20 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 48  ction Context {H
2ec30 31 36 32 31 30 7d 20 3c 53 32 30 32 30 30 3e 0a  16210} <S20200>.
2ec40 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d  **.** The implem
2ec50 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72  entation of aggr
2ec60 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2ec70 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72 6f 75  ons use this rou
2ec80 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  tine to allocate
2ec90 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72 65 20  .** a structure 
2eca0 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69  for storing thei
2ecb0 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  r state..**.** T
2ecc0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
2ecd0 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
2ece0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f  ate_context() ro
2ecf0 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
2ed00 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69 63 75  for a.** particu
2ed10 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c 20 53  lar aggregate, S
2ed20 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20  QLite allocates 
2ed30 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79  nBytes of memory
2ed40 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61  , zeroes out tha
2ed50 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e 64  t.** memory, and
2ed60 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2ed70 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73 65 63  er to it. On sec
2ed80 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2ed90 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  nt calls to.** s
2eda0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2edb0 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74  _context() for t
2edc0 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
2edd0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78  e function index
2ede0 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75  ,.** the same bu
2edf0 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  ffer is returned
2ee00 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  . The implementa
2ee10 74 69 6f 6e 20 6f 66 20 74 68 65 20 61 67 67 72  tion of the aggr
2ee20 65 67 61 74 65 20 63 61 6e 20 75 73 65 0a 2a 2a  egate can use.**
2ee30 20 74 68 65 20 72 65 74 75 72 6e 65 64 20 62 75   the returned bu
2ee40 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61  ffer to accumula
2ee50 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  te data..**.** S
2ee60 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
2ee70 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 61 6c  lly frees the al
2ee80 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72 20 77  located buffer w
2ee90 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
2eea0 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c  e.** query concl
2eeb0 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
2eec0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2eed0 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79  should be a copy
2eee0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
2eef0 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51  te3_context | SQ
2ef00 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65  L function conte
2ef10 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20  xt] that is the 
2ef20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a  first parameter.
2ef30 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
2ef40 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
2ef50 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61  implements the a
2ef60 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
2ef70 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
2ef80 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
2ef90 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
2efa0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
2efb0 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67  ch.** the aggreg
2efc0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2efd0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a   is running..**.
2efe0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2eff0 2a 0a 2a 2a 20 7b 48 31 36 32 31 31 7d 20 54 68  *.** {H16211} Th
2f000 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69  e first invocati
2f010 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 61  on of [sqlite3_a
2f020 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2f030 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20 20 20  (C,N)] for.**   
2f040 20 20 20 20 20 20 20 61 20 70 61 72 74 69 63 75         a particu
2f050 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  lar instance of 
2f060 61 6e 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  an aggregate fun
2f070 63 74 69 6f 6e 20 28 66 6f 72 20 61 20 70 61 72  ction (for a par
2f080 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20 20 20  ticular.**      
2f090 20 20 20 20 63 6f 6e 74 65 78 74 20 43 29 20 63      context C) c
2f0a0 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
2f0b0 61 6c 6c 6f 63 61 74 65 20 4e 20 62 79 74 65 73  allocate N bytes
2f0c0 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 20   of memory,.**  
2f0d0 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 68 61          zero tha
2f0e0 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
2f0f0 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 20 74  turn a pointer t
2f100 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  o the allocated 
2f110 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  memory..**.** {H
2f120 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65 6d 6f  16213} If a memo
2f130 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
2f140 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
2f150 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  g.**          [s
2f160 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2f170 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 74  _context(C,N)] t
2f180 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
2f190 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 0a 2a   returns 0..**.*
2f1a0 2a 20 7b 48 31 36 32 31 35 7d 20 53 65 63 6f 6e  * {H16215} Secon
2f1b0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
2f1c0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 0a   invocations of.
2f1d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2f1e0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2f1f0 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72  ontext(C,N)] for
2f200 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74 65 78   the same contex
2f210 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a 20 20  t pointer C.**  
2f220 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65 20 74          ignore t
2f230 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 61  he N parameter a
2f240 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e  nd return a poin
2f250 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d 65 0a  ter to the same.
2f260 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c 6f 63  **          bloc
2f270 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65 74 75  k of memory retu
2f280 72 6e 65 64 20 62 79 20 74 68 65 20 66 69 72 73  rned by the firs
2f290 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  t invocation..**
2f2a0 0a 2a 2a 20 7b 48 31 36 32 31 37 7d 20 54 68 65  .** {H16217} The
2f2b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
2f2c0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 61 67  d by [sqlite3_ag
2f2d0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2f2e0 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20  C,N)] is.**     
2f2f0 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63 61 6c       automatical
2f300 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68 65 20  ly freed on the 
2f310 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  next call to [sq
2f320 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
2f330 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
2f340 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2f350 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  )] for the [prep
2f360 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f370 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20  containing.**   
2f380 20 20 20 20 20 20 20 74 68 65 20 61 67 67 72 65         the aggre
2f390 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 61 73  gate function as
2f3a0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 63 6f  sociated with co
2f3b0 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f 69 64  ntext C..*/.void
2f3c0 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
2f3d0 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
2f3e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2f3f0 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
2f400 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
2f410 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
2f420 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c 53 32  ons {H16240} <S2
2f430 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0200>.**.** The 
2f440 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2f450 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
2f460 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
2f470 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
2f480 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
2f490 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
2f4a0 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
2f4b0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
2f4c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f4d0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
2f4e0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2f4f0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
2f500 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
2f510 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
2f520 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
2f530 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
2f540 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a  nction. {END}.**
2f550 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
2f560 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2f570 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
2f580 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
2f590 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2f5a0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2f5b0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  n is running..**
2f5c0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
2f5d0 2a 2a 0a 2a 2a 20 7b 48 31 36 32 34 33 7d 20 54  **.** {H16243} T
2f5e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  he [sqlite3_user
2f5f0 5f 64 61 74 61 28 43 29 5d 20 69 6e 74 65 72 66  _data(C)] interf
2f600 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
2f610 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  py of the.**    
2f620 20 20 20 20 20 20 50 20 70 6f 69 6e 74 65 72 20        P pointer 
2f630 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
2f640 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2f650 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  n(D,X,N,E,P,F,S,
2f660 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  L)].**          
2f670 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  or [sqlite3_crea
2f680 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 44 2c  te_function16(D,
2f690 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20  X,N,E,P,F,S,L)] 
2f6a0 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20 20 20  call that.**    
2f6b0 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64        registered
2f6c0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2f6d0 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  n associated wit
2f6e0 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  h [sqlite3_conte
2f6f0 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  xt] C..*/.void *
2f700 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2f710 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
2f720 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2f730 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
2f740 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
2f750 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d  nctions {H16250}
2f760 20 3c 53 36 30 36 30 30 3e 3c 53 32 30 32 30 30   <S60600><S20200
2f770 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
2f780 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2f790 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
2f7a0 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
2f7b0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
2f7c0 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
2f7d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2f7e0 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
2f7f0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
2f800 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f810 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
2f820 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2f830 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
2f840 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
2f850 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
2f860 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
2f870 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
2f880 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e  nction..**.** IN
2f890 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2f8a0 7b 48 31 36 32 35 33 7d 20 54 68 65 20 5b 73 71  {H16253} The [sq
2f8b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2f8c0 5f 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e 74 65  _handle(C)] inte
2f8d0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2f8e0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20  copy of the.**  
2f8f0 20 20 20 20 20 20 20 20 44 20 70 6f 69 6e 74 65          D pointe
2f900 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  r from the [sqli
2f910 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f920 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  ion(D,X,N,E,P,F,
2f930 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,L)].**        
2f940 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72    or [sqlite3_cr
2f950 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2f960 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
2f970 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20  ] call that.**  
2f980 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
2f990 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ed the SQL funct
2f9a0 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77  ion associated w
2f9b0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ith [sqlite3_con
2f9c0 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71 6c 69  text] C..*/.sqli
2f9d0 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e  te3 *sqlite3_con
2f9e0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73  text_db_handle(s
2f9f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2fa00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2fa10 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
2fa20 6c 69 61 72 79 20 44 61 74 61 20 7b 48 31 36 32  liary Data {H162
2fa30 37 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  70} <S20200>.**.
2fa40 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
2fa50 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d   two functions m
2fa60 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63  ay be used by sc
2fa70 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
2fa80 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
2fa90 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68  te metadata with
2faa0 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
2fab0 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
2fac0 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
2fad0 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
2fae0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
2faf0 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
2fb00 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
2fb10 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
2fb20 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
2fb30 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
2fb40 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61  ated metadata ma
2fb50 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
2fb60 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75  This may.** be u
2fb70 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
2fb80 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c  , to add a regul
2fb90 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
2fba0 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a  tching scalar.**
2fbb0 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
2fbc0 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
2fbd0 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
2fbe0 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f  xpression is sto
2fbf0 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
2fc00 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
2fc10 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
2fc20 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
2fc30 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
2fc40 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
2fc50 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
2fc60 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
2fc70 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
2fc80 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
2fc90 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
2fca0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
2fcb0 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
2fcc0 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
2fcd0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
2fce0 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
2fcf0 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
2fd00 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
2fd10 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
2fd20 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
2fd30 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2fd40 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
2fd50 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
2fd60 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
2fd70 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
2fd80 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
2fd90 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
2fda0 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
2fdb0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2fdc0 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f   function. If no
2fdd0 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65   metadata has be
2fde0 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20  en ever.** been 
2fdf0 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20  set for the Nth 
2fe00 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
2fe10 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20  function, or if 
2fe20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2fe30 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61  g.** function pa
2fe40 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e  rameter has chan
2fe50 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65  ged since the me
2fe60 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c  ta-data was set,
2fe70 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
2fe80 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72  _get_auxdata() r
2fe90 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
2fea0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
2feb0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
2fec0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
2fed0 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64   saves the metad
2fee0 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ata.** pointed t
2fef0 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72  o by its 3rd par
2ff00 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65  ameter as the me
2ff10 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
2ff20 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
2ff30 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2ff40 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2ff50 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ion.  Subsequent
2ff60 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
2ff70 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2ff80 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  () might return 
2ff90 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74  this data, if it
2ffa0 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e   has.** not been
2ffb0 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49   destroyed..** I
2ffc0 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  f it is not NULL
2ffd0 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  , SQLite will in
2ffe0 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
2fff0 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  tor.** function 
30000 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68  given by the 4th
30010 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
30020 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
30030 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65  a() on.** the me
30040 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20  tadata when the 
30050 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  corresponding fu
30060 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
30070 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77   changes.** or w
30080 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
30090 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c  ement completes,
300a0 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
300b0 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51   first..**.** SQ
300c0 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20  Lite is free to 
300d0 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63  call the destruc
300e0 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74  tor and drop met
300f0 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20  adata on any.** 
30100 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79  parameter of any
30110 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79   function at any
30120 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79   time.  The only
30130 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68   guarantee is th
30140 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75  at.** the destru
30150 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c  ctor will be cal
30160 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d  led before the m
30170 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70  etadata is dropp
30180 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61  ed..**.** In pra
30190 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20  ctice, metadata 
301a0 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74  is preserved bet
301b0 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61  ween function ca
301c0 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65  lls for.** expre
301d0 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ssions that are 
301e0 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70  constant at comp
301f0 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69  ile time. This i
30200 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a  ncludes literal.
30210 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 53 51  ** values and SQ
30220 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a  L variables..**.
30230 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
30240 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
30250 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
30260 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
30270 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
30280 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
30290 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
302a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 32 7d 20  .**.** {H16272} 
302b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  The [sqlite3_get
302c0 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d 20 69  _auxdata(C,N)] i
302d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
302e0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
302f0 20 20 20 20 20 20 20 74 6f 20 6d 65 74 61 64 61         to metada
30300 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
30310 74 68 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d  th the Nth param
30320 65 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20  eter of the SQL 
30330 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  function.**     
30340 20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e 74 65       whose conte
30350 78 74 20 69 73 20 43 2c 20 6f 72 20 4e 55 4c 4c  xt is C, or NULL
30360 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   if there is no 
30370 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
30380 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
30390 77 69 74 68 20 74 68 61 74 20 70 61 72 61 6d 65  with that parame
303a0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  ter..**.** {H162
303b0 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  74} The [sqlite3
303c0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
303d0 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  ,P,D)] interface
303e0 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74 61 64   assigns a metad
303f0 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ata.**          
30400 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74 68 65  pointer P to the
30410 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   Nth parameter o
30420 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
30430 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 78 74 20  on with context 
30440 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 36  C..**.** {H16276
30450 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  } SQLite will in
30460 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
30470 74 6f 72 20 44 20 77 69 74 68 20 61 20 73 69 6e  tor D with a sin
30480 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  gle argument.** 
30490 20 20 20 20 20 20 20 20 20 77 68 69 63 68 20 69           which i
304a0 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 70  s the metadata p
304b0 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f 77 69  ointer P followi
304c0 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  ng a call to.** 
304d0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
304e0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
304f0 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53 51 4c  N,P,D)] when SQL
30500 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f  ite ceases to ho
30510 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ld.**          t
30520 68 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a 2a 0a  he metadata..**.
30530 2a 2a 20 7b 48 31 36 32 37 37 7d 20 53 51 4c 69  ** {H16277} SQLi
30540 74 65 20 63 65 61 73 65 73 20 74 6f 20 68 6f 6c  te ceases to hol
30550 64 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 61  d metadata for a
30560 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70  n SQL function p
30570 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
30580 20 20 20 20 20 77 68 65 6e 20 74 68 65 20 76 61       when the va
30590 6c 75 65 20 6f 66 20 74 68 61 74 20 70 61 72 61  lue of that para
305a0 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2e 0a 2a  meter changes..*
305b0 2a 0a 2a 2a 20 7b 48 31 36 32 37 38 7d 20 57 68  *.** {H16278} Wh
305c0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  en [sqlite3_set_
305d0 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29  auxdata(C,N,P,D)
305e0 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68  ] is invoked, th
305f0 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20  e destructor.** 
30600 20 20 20 20 20 20 20 20 20 69 73 20 63 61 6c 6c           is call
30610 65 64 20 66 6f 72 20 61 6e 79 20 70 72 69 6f 72  ed for any prior
30620 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
30630 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73 61  ated with the sa
30640 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20  me function.**  
30650 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20          context 
30660 43 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20  C and parameter 
30670 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 39  N..**.** {H16279
30680 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 61  } SQLite will ca
30690 6c 6c 20 64 65 73 74 72 75 63 74 6f 72 73 20 66  ll destructors f
306a0 6f 72 20 61 6e 79 20 6d 65 74 61 64 61 74 61 20  or any metadata 
306b0 69 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a 2a 2a  it is holding.**
306c0 20 20 20 20 20 20 20 20 20 20 69 6e 20 61 20 70            in a p
306d0 61 72 74 69 63 75 6c 61 72 20 5b 70 72 65 70 61  articular [prepa
306e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
306f0 20 77 68 65 6e 20 65 69 74 68 65 72 0a 2a 2a 20   when either.** 
30700 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
30710 33 5f 72 65 73 65 74 28 53 29 5d 20 6f 72 20 5b  3_reset(S)] or [
30720 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
30730 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a  (S)] is called..
30740 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
30750 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _get_auxdata(sql
30760 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
30770 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69  nt N);.void sqli
30780 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
30790 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
307a0 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20  , int N, void*, 
307b0 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29  void (*)(void*))
307c0 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
307d0 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65  EF: Constants De
307e0 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44  fining Special D
307f0 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69  estructor Behavi
30800 6f 72 20 7b 48 31 30 32 38 30 7d 20 3c 53 33 30  or {H10280} <S30
30810 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  100>.**.** These
30820 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c   are special val
30830 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74  ues for the dest
30840 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70  ructor that is p
30850 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
30860 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e  ** final argumen
30870 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  t to routines li
30880 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ke [sqlite3_resu
30890 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20  lt_blob()].  If 
308a0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
308b0 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51  * argument is SQ
308c0 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20  LITE_STATIC, it 
308d0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
308e0 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69  ontent pointer i
308f0 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e  s constant.** an
30900 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61  d will never cha
30910 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f  nge.  It does no
30920 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73  t need to be des
30930 74 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a 2a 20  troyed.  The.** 
30940 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
30950 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61   value means tha
30960 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69  t the content wi
30970 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65  ll likely change
30980 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20   in.** the near 
30990 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20  future and that 
309a0 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61  SQLite should ma
309b0 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ke its own priva
309c0 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68  te copy of.** th
309d0 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65  e content before
309e0 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
309f0 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73  * The typedef is
30a00 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f   necessary to wo
30a10 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65  rk around proble
30a20 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a  ms in certain.**
30a30 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20   C++ compilers. 
30a40 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39   See ticket #219
30a50 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f  1..*/.typedef vo
30a60 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73  id (*sqlite3_des
30a70 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f  tructor_type)(vo
30a80 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  id*);.#define SQ
30a90 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20  LITE_STATIC     
30aa0 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
30ab0 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64  uctor_type)0).#d
30ac0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
30ad0 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74  NSIENT   ((sqlit
30ae0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
30af0 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  pe)-1)../*.** CA
30b00 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20  PI3REF: Setting 
30b10 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e  The Result Of An
30b20 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 48   SQL Function {H
30b30 31 36 34 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a  16400} <S20200>.
30b40 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
30b50 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79  ines are used by
30b60 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46   the xFunc or xF
30b70 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74  inal callbacks t
30b80 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  hat.** implement
30b90 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
30ba0 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  nd aggregates.  
30bb0 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  See.** [sqlite3_
30bc0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
30bd0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
30be0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
30bf0 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69  6()].** for addi
30c00 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
30c10 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on..**.** These 
30c20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76  functions work v
30c30 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68  ery much like th
30c40 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  e [parameter bin
30c50 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  ding] family of.
30c60 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  ** functions use
30c70 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73  d to bind values
30c80 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
30c90 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20  ers in prepared 
30ca0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52  statements..** R
30cb0 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c  efer to the [SQL
30cc0 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75   parameter] docu
30cd0 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
30ce0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
30cf0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
30d00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
30d10 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20  lob() interface 
30d20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
30d30 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
30d40 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
30d50 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
30d60 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e  e BLOB whose con
30d70 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a  tent is pointed.
30d80 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ** to by the sec
30d90 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  ond parameter an
30da0 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74  d which is N byt
30db0 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20  es long where N 
30dc0 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20  is the.** third 
30dd0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
30de0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
30df0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69  ult_zeroblob() i
30e00 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68  nterfaces set th
30e10 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
30e20 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
30e30 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
30e40 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e  to be a BLOB con
30e50 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
30e60 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20  .** bytes and N 
30e70 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77  bytes in size, w
30e80 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61  here N is the va
30e90 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70  lue of the 2nd p
30ea0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
30eb0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
30ec0 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65  lt_double() inte
30ed0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
30ee0 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
30ef0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
30f00 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
30f10 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70   be a floating p
30f20 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69  oint value speci
30f30 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32  fied.** by its 2
30f40 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
30f50 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
30f60 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
30f70 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
30f80 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74  _error16() funct
30f90 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68  ions.** cause th
30fa0 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51  e implemented SQ
30fb0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68  L function to th
30fc0 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  row an exception
30fd0 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  ..** SQLite uses
30fe0 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
30ff0 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
31000 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
31010 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
31020 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
31030 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31040 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
31050 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
31060 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69 74 65  message.  SQLite
31070 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
31080 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
31090 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
310a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
310b0 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 53 51  r() as UTF-8. SQ
310c0 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
310d0 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
310e0 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
310f0 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
31100 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  TF-16 in native.
31110 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
31120 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
31130 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
31140 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
31150 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
31160 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
31170 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
31180 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
31190 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
311a0 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
311b0 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
311c0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
311d0 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 68  er..** If the th
311e0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
311f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31200 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
31210 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31220 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
31230 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
31240 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
31250 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
31260 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
31270 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
31280 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
31290 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65   message..** The
312a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
312b0 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
312c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
312d0 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  16().** routines
312e0 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20   make a private 
312f0 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f  copy of the erro
31300 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62  r message text b
31310 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65  efore.** they re
31320 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68  turn.  Hence, th
31330 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
31340 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74  on can deallocat
31350 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74  e or.** modify t
31360 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68  he text after th
31370 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75  ey return withou
31380 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73  t harm..** The s
31390 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
313a0 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
313b0 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
313c0 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
313d0 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
313e0 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
313f0 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
31400 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 66 61  nction.  By defa
31410 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f  ult,.** the erro
31420 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45  r code is SQLITE
31430 5f 45 52 52 4f 52 2e 20 20 41 20 73 75 62 73 65  _ERROR.  A subse
31440 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
31450 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31460 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
31470 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
31480 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
31490 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
314a0 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
314b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
314c0 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74  ult_toobig() int
314d0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
314e0 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
314f0 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
31500 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69  ting that a stri
31510 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f  ng or BLOB is to
31520 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65   long to represe
31530 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  nt..**.** The sq
31540 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d  lite3_result_nom
31550 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  em() interface c
31560 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
31570 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a  throw an error.*
31580 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  * indicating tha
31590 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  t a memory alloc
315a0 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a  ation failed..**
315b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
315c0 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74  result_int() int
315d0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
315e0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
315f0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
31600 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
31610 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32  ion to be the 32
31620 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
31630 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
31640 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
31650 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73  gument..** The s
31660 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
31670 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
31680 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
31690 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
316a0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
316b0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
316c0 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69  be the 64-bit si
316d0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
316e0 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
316f0 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
31700 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
31710 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29  e3_result_null()
31720 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
31730 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
31740 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
31750 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
31760 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55  unction to be NU
31770 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  LL..**.** The sq
31780 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31790 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73  t(), sqlite3_res
317a0 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  ult_text16(),.**
317b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
317c0 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20  text16le(), and 
317d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
317e0 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66  ext16be() interf
317f0 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20  aces.** set the 
31800 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
31810 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
31820 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
31830 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74   to be.** a text
31840 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
31850 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20   represented as 
31860 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61  UTF-8, UTF-16 na
31870 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c  tive byte order,
31880 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
31890 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e endian, or UTF
318a0 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20  -16 big endian, 
318b0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
318c0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68   SQLite takes th
318d0 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
318e0 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
318f0 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
31900 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
31910 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
31920 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
31930 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33  ces..** If the 3
31940 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
31950 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
31960 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
31970 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
31980 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
31990 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
319a0 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
319b0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
319c0 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
319d0 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
319e0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
319f0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
31a00 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31a10 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
31a20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
31a30 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79   then as many by
31a40 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
31a50 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74  ers) of the text
31a60 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
31a70 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
31a80 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73  ter are taken as
31a90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
31aa0 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63  -defined.** func
31ab0 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  tion result..** 
31ac0 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
31ad0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
31ae0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
31af0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
31b00 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
31b10 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e  _blob is a non-N
31b20 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
31b30 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74  n SQLite calls t
31b40 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  hat.** function 
31b50 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  as the destructo
31b60 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72  r on the text or
31b70 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65   BLOB result whe
31b80 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
31b90 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
31ba0 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68  result..** If th
31bb0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
31bc0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
31bd0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
31be0 72 66 61 63 65 73 20 6f 72 0a 2a 2a 20 73 71 6c  rfaces or.** sql
31bf0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
31c00 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
31c10 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
31c20 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c  STATIC, then SQL
31c30 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74  ite.** assumes t
31c40 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20  hat the text or 
31c50 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69  BLOB result is i
31c60 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65  n constant space
31c70 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a   and does not.**
31c80 20 63 6f 70 79 20 74 68 65 20 69 74 20 6f 72 20   copy the it or 
31c90 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f  call a destructo
31ca0 72 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  r when it has fi
31cb0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
31cc0 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20  t result..** If 
31cd0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
31ce0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
31cf0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
31d00 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
31d10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
31d20 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
31d30 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
31d40 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74  E_TRANSIENT.** t
31d50 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  hen SQLite makes
31d60 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72   a copy of the r
31d70 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65  esult into space
31d80 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a   obtained from.*
31d90 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
31da0 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65  malloc()] before
31db0 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
31dc0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
31dd0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
31de0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
31df0 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
31e00 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
31e10 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
31e20 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a  o be a copy the.
31e30 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
31e40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
31e50 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20  bject specified 
31e60 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
31e70 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20 73 71  eter.  The.** sq
31e80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
31e90 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
31ea0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
31eb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
31ec0 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
31ed0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
31ee0 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
31ef0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
31f00 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
31f10 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
31f20 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
31f30 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
31f40 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
31f50 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74 65 64 20  ** A [protected 
31f60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
31f70 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73  bject may always
31f80 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61   be used where a
31f90 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
31fa0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
31fb0 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69   object is requi
31fc0 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a  red, so either.*
31fd0 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74  * kind of [sqlit
31fe0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
31ff0 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74   can be used wit
32000 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  h this interface
32010 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65  ..**.** If these
32020 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
32030 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e  lled from within
32040 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74   the different t
32050 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68  hread.** than th
32060 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67  e one containing
32070 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
32080 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
32090 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a  n that received.
320a0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
320b0 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72  context] pointer
320c0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
320d0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
320e0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
320f0 2a 0a 2a 2a 20 7b 48 31 36 34 30 33 7d 20 54 68  *.** {H16403} Th
32100 65 20 64 65 66 61 75 6c 74 20 72 65 74 75 72 6e  e default return
32110 20 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 79 20   value from any 
32120 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
32130 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  NULL..**.** {H16
32140 34 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  406} The [sqlite
32150 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c  3_result_blob(C,
32160 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  V,N,D)] interfac
32170 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
32180 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
32190 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
321a0 6f 6e 20 43 20 74 6f 20 62 65 20 61 20 42 4c 4f  on C to be a BLO
321b0 42 20 74 68 61 74 20 69 73 20 4e 20 62 79 74 65  B that is N byte
321c0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  s.**          in
321d0 20 6c 65 6e 67 74 68 20 61 6e 64 20 77 69 74 68   length and with
321e0 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 64   content pointed
321f0 20 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a 2a 20   to by V..**.** 
32200 7b 48 31 36 34 30 39 7d 20 54 68 65 20 5b 73 71  {H16409} The [sq
32210 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
32220 62 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65 72 66  ble(C,V)] interf
32230 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
32240 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
32250 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
32260 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
32270 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
32280 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  value V..**.** {
32290 48 31 36 34 31 32 7d 20 54 68 65 20 5b 73 71 6c  H16412} The [sql
322a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
322b0 72 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66  r(C,V,N)] interf
322c0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ace changes the 
322d0 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
322e0 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63     value of func
322f0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20  tion C to be an 
32300 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65  exception with e
32310 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20  rror code.**    
32320 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52        [SQLITE_ER
32330 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 2d 38  ROR] and a UTF-8
32340 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 63   error message c
32350 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20  opied from V up 
32360 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
32370 20 20 20 66 69 72 73 74 20 7a 65 72 6f 20 62 79     first zero by
32380 74 65 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62 79  te or until N by
32390 74 65 73 20 61 72 65 20 72 65 61 64 20 69 66 20  tes are read if 
323a0 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a  N is positive..*
323b0 2a 0a 2a 2a 20 7b 48 31 36 34 31 35 7d 20 54 68  *.** {H16415} Th
323c0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
323d0 74 5f 65 72 72 6f 72 31 36 28 43 2c 56 2c 4e 29  t_error16(C,V,N)
323e0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
323f0 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
32400 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
32410 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
32420 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f  o be an exceptio
32430 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64  n with error cod
32440 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  e.**          [S
32450 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64  QLITE_ERROR] and
32460 20 61 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65   a UTF-16 native
32470 20 62 79 74 65 20 6f 72 64 65 72 20 65 72 72 6f   byte order erro
32480 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20  r message.**    
32490 20 20 20 20 20 20 63 6f 70 69 65 64 20 66 72 6f        copied fro
324a0 6d 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69  m V up to the fi
324b0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
324c0 74 6f 72 20 6f 72 20 75 6e 74 69 6c 20 4e 20 62  tor or until N b
324d0 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ytes.**         
324e0 20 61 72 65 20 72 65 61 64 20 69 66 20 4e 20 69   are read if N i
324f0 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a 0a 2a  s positive..**.*
32500 2a 20 7b 48 31 36 34 31 38 7d 20 54 68 65 20 5b  * {H16418} The [
32510 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32520 72 72 6f 72 5f 74 6f 6f 62 69 67 28 43 29 5d 20  rror_toobig(C)] 
32530 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
32540 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20  s the return.** 
32550 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
32560 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43  f the function C
32570 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74   to be an except
32580 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63  ion with error c
32590 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
325a0 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20  [SQLITE_TOOBIG] 
325b0 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61  and an appropria
325c0 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  te error message
325d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 31 7d  ..**.** {H16421}
325e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
325f0 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
32600 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (C)] interface c
32610 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72  hanges the retur
32620 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  n.**          va
32630 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  lue of the funct
32640 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65  ion C to be an e
32650 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72  xception with er
32660 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20  ror code.**     
32670 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d       [SQLITE_NOM
32680 45 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f  EM] and an appro
32690 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73  priate error mes
326a0 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  sage..**.** {H16
326b0 34 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  424} The [sqlite
326c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
326d0 6f 64 65 28 43 2c 45 29 5d 20 69 6e 74 65 72 66  ode(C,E)] interf
326e0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ace changes the 
326f0 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
32700 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20     value of the 
32710 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
32720 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69   an exception wi
32730 74 68 20 65 72 72 6f 72 20 63 6f 64 65 20 45 2e  th error code E.
32740 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 54 68 65  .**          The
32750 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
32760 65 78 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  ext is unchanged
32770 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32 37 7d  ..**.** {H16427}
32780 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
32790 73 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d 20 69  sult_int(C,V)] i
327a0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
327b0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
327c0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
327d0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
327e0 65 20 74 68 65 20 33 32 2d 62 69 74 20 69 6e 74  e the 32-bit int
327f0 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a  eger value V..**
32800 0a 2a 2a 20 7b 48 31 36 34 33 30 7d 20 54 68 65  .** {H16430} The
32810 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
32820 5f 69 6e 74 36 34 28 43 2c 56 29 5d 20 69 6e 74  _int64(C,V)] int
32830 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
32840 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
32850 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
32860 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
32870 74 68 65 20 36 34 2d 62 69 74 20 69 6e 74 65 67  the 64-bit integ
32880 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a  er value V..**.*
32890 2a 20 7b 48 31 36 34 33 33 7d 20 54 68 65 20 5b  * {H16433} The [
328a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
328b0 75 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66 61 63  ull(C)] interfac
328c0 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
328d0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
328e0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
328f0 6f 6e 20 43 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  on C to be NULL.
32900 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 36 7d 20  .**.** {H16436} 
32910 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
32920 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44  ult_text(C,V,N,D
32930 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
32940 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
32950 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
32960 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
32970 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d 38 20  to be the UTF-8 
32980 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  string.**       
32990 20 20 20 56 20 75 70 20 74 6f 20 74 68 65 20 66     V up to the f
329a0 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69  irst zero if N i
329b0 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20  s negative.**   
329c0 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69         or the fi
329d0 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56  rst N bytes of V
329e0 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67   if N is non-neg
329f0 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ative..**.** {H1
32a00 36 34 33 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  6439} The [sqlit
32a10 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
32a20 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72  (C,V,N,D)] inter
32a30 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
32a40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
32a50 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
32a60 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68  ction C to be th
32a70 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  e UTF-16 native 
32a80 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
32a90 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20         string V 
32aa0 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
32ab0 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67  zero if N is neg
32ac0 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  ative.**        
32ad0 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e    or the first N
32ae0 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e   bytes of V if N
32af0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
32b00 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 32 7d  ..**.** {H16442}
32b10 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
32b20 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c  sult_text16be(C,
32b30 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  V,N,D)] interfac
32b40 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
32b50 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
32b60 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
32b70 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55  on C to be the U
32b80 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e  TF-16 big-endian
32b90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
32ba0 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20  ing V up to the 
32bb0 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20  first zero if N 
32bc0 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20  is negative.**  
32bd0 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66          or the f
32be0 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 72 20  irst N bytes or 
32bf0 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  V if N is non-ne
32c00 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  gative..**.** {H
32c10 31 36 34 34 35 7d 20 54 68 65 20 5b 73 71 6c 69  16445} The [sqli
32c20 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
32c30 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e  6le(C,V,N,D)] in
32c40 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20  terface changes 
32c50 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
32c60 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
32c70 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
32c80 20 74 68 65 20 55 54 46 2d 31 36 20 6c 69 74 74   the UTF-16 litt
32c90 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20  le-endian.**    
32ca0 20 20 20 20 20 20 73 74 72 69 6e 67 20 56 20 75        string V u
32cb0 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
32cc0 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61  ero if N is nega
32cd0 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  tive.**         
32ce0 20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20   or the first N 
32cf0 62 79 74 65 73 20 6f 66 20 56 20 69 66 20 4e 20  bytes of V if N 
32d00 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e  is non-negative.
32d10 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 38 7d 20  .**.** {H16448} 
32d20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
32d30 75 6c 74 5f 76 61 6c 75 65 28 43 2c 56 29 5d 20  ult_value(C,V)] 
32d40 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
32d50 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
32d60 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
32d70 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
32d80 62 65 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  be the [unprotec
32d90 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
32da0 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  e].**          o
32db0 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b  bject V..**.** {
32dc0 48 31 36 34 35 31 7d 20 54 68 65 20 5b 73 71 6c  H16451} The [sql
32dd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
32de0 62 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74 65 72  blob(C,N)] inter
32df0 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65  face changes the
32e00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
32e10 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e  urn value of fun
32e20 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
32e30 20 4e 2d 62 79 74 65 20 42 4c 4f 42 20 6f 66 20   N-byte BLOB of 
32e40 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a 2a 2a  all zeros..**.**
32e50 20 7b 48 31 36 34 35 34 7d 20 54 68 65 20 5b 73   {H16454} The [s
32e60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32e70 72 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ror()] and [sqli
32e80 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
32e90 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  16()].**        
32ea0 20 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b    interfaces mak
32eb0 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 69  e a copy of thei
32ec0 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  r error message 
32ed0 73 74 72 69 6e 67 73 20 62 65 66 6f 72 65 0a 2a  strings before.*
32ee0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
32ef0 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ning..**.** {H16
32f00 34 35 37 7d 20 49 66 20 74 68 65 20 44 20 64 65  457} If the D de
32f10 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74  structor paramet
32f20 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  er to [sqlite3_r
32f30 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
32f40 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
32f50 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
32f60 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
32f70 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  , [sqlite3_resul
32f80 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
32f90 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
32fa0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32fb0 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
32fc0 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
32fd0 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
32fe0 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
32ff0 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63 6f 6e  N,D)] is the con
33000 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54  stant [SQLITE_ST
33010 41 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ATIC].**        
33020 20 20 74 68 65 6e 20 6e 6f 20 64 65 73 74 72 75    then no destru
33030 63 74 6f 72 20 69 73 20 65 76 65 72 20 63 61 6c  ctor is ever cal
33040 6c 65 64 20 6f 6e 20 74 68 65 20 70 6f 69 6e 74  led on the point
33050 65 72 20 56 20 61 6e 64 20 53 51 4c 69 74 65 0a  er V and SQLite.
33060 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73 75  **          assu
33070 6d 65 73 20 74 68 61 74 20 56 20 69 73 20 69 6d  mes that V is im
33080 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b  mutable..**.** {
33090 48 31 36 34 36 30 7d 20 49 66 20 74 68 65 20 44  H16460} If the D
330a0 20 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61   destructor para
330b0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
330c0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c  3_result_blob(C,
330d0 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
330e0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
330f0 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c  sult_text(C,V,N,
33100 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  D)], [sqlite3_re
33110 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c  sult_text16(C,V,
33120 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  N,D)],.**       
33130 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
33140 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c  lt_text16be(C,V,
33150 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  N,D)], or.**    
33160 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72        [sqlite3_r
33170 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43  esult_text16le(C
33180 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20  ,V,N,D)] is the 
33190 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20 20 20  constant.**     
331a0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 52 41       [SQLITE_TRA
331b0 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 74 68 65  NSIENT] then the
331c0 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6b 65   interfaces make
331d0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
331e0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  **          cont
331f0 65 6e 74 20 6f 66 20 56 20 61 6e 64 20 72 65 74  ent of V and ret
33200 61 69 6e 73 20 74 68 65 20 63 6f 70 79 2e 0a 2a  ains the copy..*
33210 2a 0a 2a 2a 20 7b 48 31 36 34 36 33 7d 20 49 66  *.** {H16463} If
33220 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f   the D destructo
33230 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  r parameter to [
33240 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
33250 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  lob(C,V,N,D)],.*
33260 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
33270 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
33280 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69  C,V,N,D)], [sqli
33290 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
332a0 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  6(C,V,N,D)],.** 
332b0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
332c0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
332d0 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a  e(C,V,N,D)], or.
332e0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
332f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33300 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  16le(C,V,N,D)] i
33310 73 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f 74 68  s some value oth
33320 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  er than.**      
33330 20 20 20 20 74 68 65 20 63 6f 6e 73 74 61 6e 74      the constant
33340 73 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  s [SQLITE_STATIC
33350 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 54 52  ] and [SQLITE_TR
33360 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 0a 2a 2a  ANSIENT] then.**
33370 20 20 20 20 20 20 20 20 20 20 53 51 4c 69 74 65            SQLite
33380 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
33390 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69   destructor D wi
333a0 74 68 20 56 20 61 73 20 69 74 73 20 6f 6e 6c 79  th V as its only
333b0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20 20 20   argument.**    
333c0 20 20 20 20 20 20 77 68 65 6e 20 69 74 20 68 61        when it ha
333d0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
333e0 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a 2f 0a  the V value..*/.
333f0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33400 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
33410 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
33420 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
33430 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
33440 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
33450 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
33460 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
33470 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
33480 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
33490 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
334a0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
334b0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
334c0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
334d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
334e0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
334f0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
33500 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
33510 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
33520 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
33530 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33540 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
33550 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
33560 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33570 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
33580 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
33590 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
335a0 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
335b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
335c0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
335d0 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
335e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
335f0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
33600 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
33610 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
33620 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
33630 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33640 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
33650 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
33660 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
33670 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
33680 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33690 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
336a0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
336b0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
336c0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
336d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
336e0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16le(sqlite3_con
336f0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
33700 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
33710 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
33720 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
33730 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
33740 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
33750 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
33760 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
33770 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
33780 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lue(sqlite3_cont
33790 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61  ext*, sqlite3_va
337a0 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
337b0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
337c0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  lob(sqlite3_cont
337d0 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f  ext*, int n);../
337e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
337f0 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
33800 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20 7b 48  ing Sequences {H
33810 31 36 36 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a  16600} <S20300>.
33820 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
33830 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74  tions are used t
33840 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74  o add new collat
33850 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f  ion sequences to
33860 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
33870 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
33880 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
33890 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
338a0 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
338b0 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69   the new collati
338c0 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73  on sequence is s
338d0 70 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54  pecified as a UT
338e0 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f  F-8 string.** fo
338f0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
33900 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64  _collation() and
33910 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33920 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a  collation_v2().*
33930 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73  * and a UTF-16 s
33940 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65  tring for sqlite
33950 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33960 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63  on16(). In all c
33970 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  ases.** the name
33980 20 69 73 20 70 61 73 73 65 64 20 61 73 20 74 68   is passed as th
33990 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
339a0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
339b0 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75  * The third argu
339c0 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20  ment may be one 
339d0 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73  of the constants
339e0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a   [SQLITE_UTF8],.
339f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ** [SQLITE_UTF16
33a00 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  LE] or [SQLITE_U
33a10 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74  TF16BE], indicat
33a20 69 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65  ing that the use
33a30 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f  r-supplied.** ro
33a40 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f  utine expects to
33a50 20 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74   be passed point
33a60 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65  ers to strings e
33a70 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
33a80 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  -8,.** UTF-16 li
33a90 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle-endian, or 
33aa0 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61  UTF-16 big-endia
33ab0 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
33ac0 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72   The.** third ar
33ad0 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73  gument might als
33ae0 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  o be [SQLITE_UTF
33af0 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f 20 69  16_ALIGNED] to i
33b00 6e 64 69 63 61 74 65 20 74 68 61 74 0a 2a 2a 20  ndicate that.** 
33b10 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65  the routine expe
33b20 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  cts pointers to 
33b30 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67  16-bit word alig
33b40 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f  ned strings.** o
33b50 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  f UTF-16 in the 
33b60 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
33b70 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 63 6f  r of the host co
33b80 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20  mputer..**.** A 
33b90 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75  pointer to the u
33ba0 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75  ser supplied rou
33bb0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73  tine must be pas
33bc0 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68  sed as the fifth
33bd0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49  .** argument.  I
33be0 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  f it is NULL, th
33bf0 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  is is the same a
33c00 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  s deleting the c
33c10 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
33c20 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51  ence (so that SQ
33c30 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c  Lite cannot call
33c40 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a   it anymore)..**
33c50 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61   Each time the a
33c60 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c  pplication suppl
33c70 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ied function is 
33c80 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70  invoked, it is p
33c90 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20  assed.** as its 
33ca0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
33cb0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
33cc0 69 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  id* passed as th
33cd0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
33ce0 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
33cf0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33d00 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
33d10 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
33d20 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65  ()..**.** The re
33d30 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74  maining argument
33d40 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  s to the applica
33d50 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f  tion-supplied ro
33d60 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74  utine are two st
33d70 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72  rings,.** each r
33d80 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20  epresented by a 
33d90 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70  (length, data) p
33da0 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20  air and encoded 
33db0 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a  in the encoding.
33dc0 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73  ** that was pass
33dd0 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
33de0 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68  argument when th
33df0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  e collation sequ
33e00 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69  ence was.** regi
33e10 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54  stered. {END}  T
33e20 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
33e30 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
33e40 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a   routine should.
33e50 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69  ** return negati
33e60 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69  ve, zero or posi
33e70 74 69 76 65 20 69 66 20 74 68 65 20 66 69 72 73  tive if the firs
33e80 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
33e90 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20   than,.** equal 
33ea0 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74  to, or greater t
33eb0 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 73  han the second s
33ec0 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52  tring. i.e. (STR
33ed0 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e  ING1 - STRING2).
33ee0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
33ef0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33f00 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c  ion_v2() works l
33f10 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  ike sqlite3_crea
33f20 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a  te_collation().*
33f30 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
33f40 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20   takes an extra 
33f50 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
33f60 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66  s a destructor f
33f70 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74  or.** the collat
33f80 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75  ion.  The destru
33f90 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77  ctor is called w
33fa0 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  hen the collatio
33fb0 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65  n is.** destroye
33fc0 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20  d and is passed 
33fd0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f  a copy of the fo
33fe0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76  urth parameter v
33ff0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  oid* pointer.** 
34000 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  of the sqlite3_c
34010 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
34020 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69  v2()..** Collati
34030 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65  ons are destroye
34040 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  d when they are 
34050 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61  overridden by la
34060 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  ter calls to the
34070 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72  .** collation cr
34080 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  eation functions
34090 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61   or when the [da
340a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
340b0 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20  n] is closed.** 
340c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
340d0 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  lose()]..**.** I
340e0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
340f0 20 7b 48 31 36 36 30 33 7d 20 41 20 73 75 63 63   {H16603} A succ
34100 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 74  essful call to t
34110 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
34120 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
34130 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c  ollation_v2(B,X,
34140 45 2c 50 2c 46 2c 44 29 5d 20 69 6e 74 65 72 66  E,P,F,D)] interf
34150 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ace.**          
34160 72 65 67 69 73 74 65 72 73 20 66 75 6e 63 74 69  registers functi
34170 6f 6e 20 46 20 61 73 20 74 68 65 20 63 6f 6d 70  on F as the comp
34180 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  arison function 
34190 75 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20  used to.**      
341a0 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74 20 63 6f      implement co
341b0 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 74 68 65  llation X on the
341c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
341d0 63 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a 2a 20  ction] B for.** 
341e0 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73           databas
341f0 65 73 20 68 61 76 69 6e 67 20 65 6e 63 6f 64 69  es having encodi
34200 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ng E..**.** {H16
34210 36 30 34 7d 20 53 51 4c 69 74 65 20 75 6e 64 65  604} SQLite unde
34220 72 73 74 61 6e 64 73 20 74 68 65 20 58 20 70 61  rstands the X pa
34230 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20  rameter to.**   
34240 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
34250 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34260 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29  _v2(B,X,E,P,F,D)
34270 5d 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  ] as a zero-term
34280 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  inated.**       
34290 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20     UTF-8 string 
342a0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 69 73  in which case is
342b0 20 69 67 6e 6f 72 65 64 20 66 6f 72 20 41 53 43   ignored for ASC
342c0 49 49 20 63 68 61 72 61 63 74 65 72 73 20 61 6e  II characters an
342d0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  d.**          is
342e0 20 73 69 67 6e 69 66 69 63 61 6e 74 20 66 6f 72   significant for
342f0 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61 72 61   non-ASCII chara
34300 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  cters..**.** {H1
34310 36 36 30 36 7d 20 53 75 63 63 65 73 73 69 76 65  6606} Successive
34320 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
34330 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34340 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
34350 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,D)].**         
34360 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76   with the same v
34370 61 6c 75 65 73 20 66 6f 72 20 42 2c 20 58 2c 20  alues for B, X, 
34380 61 6e 64 20 45 2c 20 6f 76 65 72 72 69 64 65 20  and E, override 
34390 70 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a 2a 20  prior values.** 
343a0 20 20 20 20 20 20 20 20 20 6f 66 20 50 2c 20 46           of P, F
343b0 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  , and D..**.** {
343c0 48 31 36 36 30 39 7d 20 49 66 20 74 68 65 20 64  H16609} If the d
343d0 65 73 74 72 75 63 74 6f 72 20 44 20 69 6e 20 5b  estructor D in [
343e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
343f0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c  ollation_v2(B,X,
34400 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20  E,P,F,D)].**    
34410 20 20 20 20 20 20 69 73 20 6e 6f 74 20 4e 55 4c        is not NUL
34420 4c 20 74 68 65 6e 20 69 74 20 69 73 20 63 61 6c  L then it is cal
34430 6c 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e  led with argumen
34440 74 20 50 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  t P when the.** 
34450 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69           collati
34460 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  ng function is d
34470 72 6f 70 70 65 64 20 62 79 20 53 51 4c 69 74 65  ropped by SQLite
34480 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 32 7d  ..**.** {H16612}
34490 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   A collating fun
344a0 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70 65 64  ction is dropped
344b0 20 77 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   when it is over
344c0 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  loaded..**.** {H
344d0 31 36 36 31 35 7d 20 41 20 63 6f 6c 6c 61 74 69  16615} A collati
344e0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  ng function is d
344f0 72 6f 70 70 65 64 20 77 68 65 6e 20 74 68 65 20  ropped when the 
34500 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34510 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
34520 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20  is closed using 
34530 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
34540 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31 38  ]..**.** {H16618
34550 7d 20 54 68 65 20 70 6f 69 6e 74 65 72 20 50 20  } The pointer P 
34560 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  in [sqlite3_crea
34570 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
34580 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a  B,X,E,P,F,D)].**
34590 20 20 20 20 20 20 20 20 20 20 69 73 20 70 61 73            is pas
345a0 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
345b0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
345c0 65 72 20 74 6f 20 74 68 65 20 63 6f 6d 70 61 72  er to the compar
345d0 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ison.**         
345e0 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20   function F for 
345f0 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69  all subsequent i
34600 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 46 2e  nvocations of F.
34610 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 31 7d 20  .**.** {H16621} 
34620 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
34630 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34640 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20  ion(B,X,E,P,F)] 
34650 69 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20  is exactly.**   
34660 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20         the same 
34670 61 73 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  as a call to [sq
34680 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34690 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 20 77 69 74  lation_v2()] wit
346a0 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  h.**          th
346b0 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72  e same parameter
346c0 73 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64 65 73  s and a NULL des
346d0 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b  tructor..**.** {
346e0 48 31 36 36 32 34 7d 20 46 6f 6c 6c 6f 77 69 6e  H16624} Followin
346f0 67 20 61 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  g a [sqlite3_cre
34700 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
34710 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 2c 0a  (B,X,E,P,F,D)],.
34720 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69  **          SQLi
34730 74 65 20 75 73 65 73 20 74 68 65 20 63 6f 6d 70  te uses the comp
34740 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  arison function 
34750 46 20 66 6f 72 20 61 6c 6c 20 74 65 78 74 20 63  F for all text c
34760 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20  omparison.**    
34770 20 20 20 20 20 20 6f 70 65 72 61 74 69 6f 6e 73        operations
34780 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
34790 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20  e connection] B 
347a0 6f 6e 20 74 65 78 74 20 76 61 6c 75 65 73 20 74  on text values t
347b0 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hat.**          
347c0 75 73 65 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  use the collatin
347d0 67 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 64  g sequence named
347e0 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32   X..**.** {H1662
347f0 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
34800 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34810 31 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d 20 77  16(B,X,E,P,F)] w
34820 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 0a 2a 2a  orks the same.**
34830 20 20 20 20 20 20 20 20 20 20 61 73 20 5b 73 71            as [sq
34840 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34850 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46  lation(B,X,E,P,F
34860 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
34870 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  he.**          c
34880 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 58 20  ollation name X 
34890 69 73 20 75 6e 64 65 72 73 74 6f 6f 64 20 61 73  is understood as
348a0 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
348b0 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
348c0 20 20 20 20 20 20 20 20 20 69 6e 73 74 65 61 64           instead
348d0 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a   of UTF-8..**.**
348e0 20 7b 48 31 36 36 33 30 7d 20 57 68 65 6e 20 6d   {H16630} When m
348f0 75 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72 69 73  ultiple comparis
34900 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  on functions are
34910 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20 74   available for t
34920 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he same.**      
34930 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20 73 65      collating se
34940 71 75 65 6e 63 65 2c 20 53 51 4c 69 74 65 20 63  quence, SQLite c
34950 68 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65 20 77  hooses the one w
34960 68 6f 73 65 20 74 65 78 74 20 65 6e 63 6f 64 69  hose text encodi
34970 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ng.**          r
34980 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 73  equires the leas
34990 74 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 76  t amount of conv
349a0 65 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68 65 20  ersion from the 
349b0 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20 20 20  default.**      
349c0 20 20 20 20 74 65 78 74 20 65 6e 63 6f 64 69 6e      text encodin
349d0 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  g of the databas
349e0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
349f0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
34a00 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  on(.  sqlite3*, 
34a10 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
34a20 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
34a30 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
34a40 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
34a50 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
34a60 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
34a70 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20  t void*).);.int 
34a80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
34a90 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73  ollation_v2(.  s
34aa0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
34ab0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
34ac0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
34ad0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
34ae0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
34af0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
34b00 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
34b10 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
34b20 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69  roy)(void*).);.i
34b30 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
34b40 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
34b50 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
34b60 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c  nst void *zName,
34b70 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
34b80 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74   .  void*,.  int
34b90 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
34ba0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
34bb0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
34bc0 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
34bd0 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
34be0 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
34bf0 73 20 7b 48 31 36 37 30 30 7d 20 3c 53 32 30 33  s {H16700} <S203
34c00 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f  00>.**.** To avo
34c10 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67  id having to reg
34c20 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74  ister all collat
34c30 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65  ion sequences be
34c40 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a  fore a database.
34c50 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20  ** can be used, 
34c60 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63  a single callbac
34c70 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  k function may b
34c80 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  e registered wit
34c90 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  h the.** [databa
34ca0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
34cb0 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  o be called when
34cc0 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65  ever an undefine
34cd0 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  d collation.** s
34ce0 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69  equence is requi
34cf0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  red..**.** If th
34d00 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65  e function is re
34d10 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74  gistered using t
34d20 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  he sqlite3_colla
34d30 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50  tion_needed() AP
34d40 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  I,.** then it is
34d50 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65   passed the name
34d60 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63  s of undefined c
34d70 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
34d80 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a  es as strings.**
34d90 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d   encoded in UTF-
34da0 38 2e 20 7b 48 31 36 37 30 33 7d 20 49 66 20 73  8. {H16703} If s
34db0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
34dc0 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75  _needed16() is u
34dd0 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  sed,.** the name
34de0 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  s are passed as 
34df0 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e  UTF-16 in machin
34e00 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
34e10 64 65 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  der..** A call t
34e20 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f  o either functio
34e30 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65  n replaces any e
34e40 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b  xisting callback
34e50 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
34e60 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
34e70 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
34e80 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
34e90 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
34ea0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
34eb0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
34ec0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
34ed0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
34ee0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
34ef0 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  16().  The secon
34f00 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
34f10 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
34f20 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74  nnection.  The t
34f30 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
34f40 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
34f50 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
34f60 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  TF16BE],.** or [
34f70 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
34f80 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
34f90 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66  most desirable f
34fa0 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
34fb0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
34fc0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
34fd0 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  ed.  The fourth 
34fe0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
34ff0 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
35000 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69  required collati
35010 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a  on sequence..**.
35020 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
35030 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
35040 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73  register the des
35050 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75  ired collation u
35060 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
35070 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
35080 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  n()], [sqlite3_c
35090 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
350a0 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
350b0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
350c0 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  ation_v2()]..**.
350d0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
350e0 2a 0a 2a 2a 20 7b 48 31 36 37 30 32 7d 20 41 20  *.** {H16702} A 
350f0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
35100 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  to [sqlite3_coll
35110 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44 2c 50  ation_needed(D,P
35120 2c 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,F)].**         
35130 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   or [sqlite3_col
35140 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
35150 44 2c 50 2c 46 29 5d 20 63 61 75 73 65 73 0a 2a  D,P,F)] causes.*
35160 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
35170 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35180 69 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f 6b 65  ion] D to invoke
35190 20 63 61 6c 6c 62 61 63 6b 20 46 20 77 69 74 68   callback F with
351a0 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20   first.**       
351b0 20 20 20 70 61 72 61 6d 65 74 65 72 20 50 20 77     parameter P w
351c0 68 65 6e 65 76 65 72 20 69 74 20 6e 65 65 64 73  henever it needs
351d0 20 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75   a comparison fu
351e0 6e 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a 2a 20  nction for a.** 
351f0 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69           collati
35200 6e 67 20 73 65 71 75 65 6e 63 65 20 74 68 61 74  ng sequence that
35210 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f   it does not kno
35220 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a 20 7b  w about..**.** {
35230 48 31 36 37 30 34 7d 20 45 61 63 68 20 73 75 63  H16704} Each suc
35240 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
35250 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
35260 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f 72 0a  on_needed()] or.
35270 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
35280 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
35290 65 65 64 65 64 31 36 28 29 5d 20 6f 76 65 72 72  eeded16()] overr
352a0 69 64 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  ides the callbac
352b0 6b 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20  k registered.** 
352c0 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20           on the 
352d0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
352e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20 70 72  onnection] by pr
352f0 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65 69 74  ior calls to eit
35300 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
35310 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
35320 20 7b 48 31 36 37 30 36 7d 20 54 68 65 20 6e 61   {H16706} The na
35330 6d 65 20 6f 66 20 74 68 65 20 72 65 71 75 65 73  me of the reques
35340 74 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ted collating fu
35350 6e 63 74 69 6f 6e 20 70 61 73 73 65 64 20 69 6e  nction passed in
35360 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
35370 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
35380 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
35390 73 20 69 6e 20 55 54 46 2d 38 20 69 66 20 74 68  s in UTF-8 if th
353a0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  e callback.**   
353b0 20 20 20 20 20 20 20 77 61 73 20 72 65 67 69 73         was regis
353c0 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  tered using [sql
353d0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
353e0 65 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  eeded()] and.** 
353f0 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 20 55           is in U
35400 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
35410 65 20 6f 72 64 65 72 20 69 66 20 74 68 65 20 63  e order if the c
35420 61 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a 20 20  allback was.**  
35430 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
35440 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
35450 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
35460 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ed16()]..*/.int 
35470 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
35480 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
35490 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
354a0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
354b0 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
354c0 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
354d0 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  r*).);.int sqlit
354e0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
354f0 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ded16(.  sqlite3
35500 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76  *, .  void*,.  v
35510 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
35520 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
35530 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  ep,const void*).
35540 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
35550 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
35560 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
35570 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
35580 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
35590 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
355a0 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
355b0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
355c0 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
355d0 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
355e0 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
355f0 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
35600 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
35610 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
35620 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
35630 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35640 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
35650 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
35660 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
35670 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
35680 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
35690 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
356a0 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
356b0 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
356c0 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
356d0 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
356e0 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
356f0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
35700 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
35710 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
35720 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
35730 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
35740 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
35750 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
35760 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
35770 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
35780 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
35790 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
357a0 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
357b0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
357c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
357d0 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
357e0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
357f0 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
35800 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
35810 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
35820 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35830 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  F: Suspend Execu
35840 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
35850 20 54 69 6d 65 20 7b 48 31 30 35 33 30 7d 20 3c   Time {H10530} <
35860 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S40410>.**.** Th
35870 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  e sqlite3_sleep(
35880 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  ) function cause
35890 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68  s the current th
358a0 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20  read to suspend 
358b0 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72  execution.** for
358c0 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62   at least a numb
358d0 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
358e0 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  ds specified in 
358f0 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  its parameter..*
35900 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72  *.** If the oper
35910 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65  ating system doe
35920 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c  s not support sl
35930 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74  eep requests wit
35940 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  h.** millisecond
35950 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e   time resolution
35960 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20  , then the time 
35970 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20  will be rounded 
35980 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61  up to.** the nea
35990 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65  rest second. The
359a0 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
359b0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
359c0 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71   actually.** req
359d0 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20  uested from the 
359e0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
359f0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
35a00 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65  .** SQLite imple
35a10 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72  ments this inter
35a20 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20  face by calling 
35a30 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20  the xSleep().** 
35a40 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
35a50 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
35a60 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  fs] object..**.*
35a70 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
35a80 0a 2a 2a 20 7b 48 31 30 35 33 33 7d 20 54 68 65  .** {H10533} The
35a90 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28   [sqlite3_sleep(
35aa0 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 6e  M)] interface in
35ab0 76 6f 6b 65 73 20 74 68 65 20 78 53 6c 65 65 70  vokes the xSleep
35ac0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 74  .**          met
35ad0 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
35ae0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 7c  lt [sqlite3_vfs|
35af0 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  VFS] in order to
35b00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 75 73  .**          sus
35b10 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 20 6f  pend execution o
35b20 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68  f the current th
35b30 72 65 61 64 20 66 6f 72 20 61 74 20 6c 65 61 73  read for at leas
35b40 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4d 20  t.**          M 
35b50 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a  milliseconds..**
35b60 0a 2a 2a 20 7b 48 31 30 35 33 36 7d 20 54 68 65  .** {H10536} The
35b70 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28   [sqlite3_sleep(
35b80 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  M)] interface re
35b90 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
35ba0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
35bb0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
35bc0 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 20 72  sleep actually r
35bd0 65 71 75 65 73 74 65 64 20 6f 66 20 74 68 65 20  equested of the 
35be0 6f 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20 20 20  operating.**    
35bf0 20 20 20 20 20 20 73 79 73 74 65 6d 2c 20 77 68        system, wh
35c00 69 63 68 20 6d 69 67 68 74 20 62 65 20 6c 61 72  ich might be lar
35c10 67 65 72 20 74 68 61 6e 20 74 68 65 20 70 61 72  ger than the par
35c20 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69 6e 74  ameter M..*/.int
35c30 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69   sqlite3_sleep(i
35c40 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
35c50 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68  3REF: Name Of Th
35c60 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67  e Folder Holding
35c70 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73   Temporary Files
35c80 20 7b 48 31 30 33 31 30 7d 20 3c 53 32 30 30 30   {H10310} <S2000
35c90 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73  0>.**.** If this
35ca0 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
35cb0 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
35cc0 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  t to a string wh
35cd0 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61  ich is.** the na
35ce0 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28  me of a folder (
35cf0 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79  a.k.a. directory
35d00 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70  ), then all temp
35d10 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63  orary files.** c
35d20 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  reated by SQLite
35d30 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20   will be placed 
35d40 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72  in that director
35d50 79 2e 20 20 49 66 20 74 68 69 73 20 76 61 72 69  y.  If this vari
35d60 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  able.** is a NUL
35d70 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
35d80 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20  SQLite performs 
35d90 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20  a search for an 
35da0 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74  appropriate.** t
35db0 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69  emporary file di
35dc0 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49  rectory..**.** I
35dd0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
35de0 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
35df0 69 61 62 6c 65 20 6f 6e 63 65 20 61 20 5b 64 61  iable once a [da
35e00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35e10 6e 5d 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 6f  n].** has been o
35e20 70 65 6e 65 64 2e 20 20 49 74 20 69 73 20 69 6e  pened.  It is in
35e30 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73  tended that this
35e40 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74   variable be set
35e50 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74   once.** as part
35e60 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74   of process init
35e70 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62  ialization and b
35e80 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65  efore any SQLite
35e90 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f   interface.** ro
35ea0 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e  utines have been
35eb0 20 63 61 6c 6c 20 61 6e 64 20 72 65 6d 61 69 6e   call and remain
35ec0 20 75 6e 63 68 61 6e 67 65 64 20 74 68 65 72 65   unchanged there
35ed0 61 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45  after..*/.SQLITE
35ee0 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71  _EXTERN char *sq
35ef0 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
35f00 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tory;../*.** CAP
35f10 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20  I3REF: Test For 
35f20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65  Auto-Commit Mode
35f30 20 7b 48 31 32 39 33 30 7d 20 3c 53 36 30 32 30   {H12930} <S6020
35f40 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
35f50 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  {autocommit mode
35f60 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  }.**.** The sqli
35f70 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
35f80 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  it() interface r
35f90 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20  eturns non-zero 
35fa0 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68  or.** zero if th
35fb0 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65  e given database
35fc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
35fd0 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f  r is not in auto
35fe0 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20  commit mode,.** 
35ff0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41  respectively.  A
36000 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
36010 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  s on by default.
36020 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  .** Autocommit m
36030 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  ode is disabled 
36040 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61  by a [BEGIN] sta
36050 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74 6f 63  tement..** Autoc
36060 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65  ommit mode is re
36070 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43  -enabled by a [C
36080 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42  OMMIT] or [ROLLB
36090 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63  ACK]..**.** If c
360a0 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20  ertain kinds of 
360b0 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20  errors occur on 
360c0 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  a statement with
360d0 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65  in a multi-state
360e0 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ment.** transact
360f0 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c  ion (errors incl
36100 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55  uding [SQLITE_FU
36110 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45  LL], [SQLITE_IOE
36120 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  RR],.** [SQLITE_
36130 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f  NOMEM], [SQLITE_
36140 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  BUSY], and [SQLI
36150 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74  TE_INTERRUPT]) t
36160 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73  hen the.** trans
36170 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  action might be 
36180 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
36190 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20  matically.  The 
361a0 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66  only way to.** f
361b0 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20  ind out whether 
361c0 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
361d0 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
361e0 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
361f0 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72   after.** an err
36200 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69  or is to use thi
36210 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
36220 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
36230 0a 2a 2a 20 7b 48 31 32 39 33 31 7d 20 54 68 65  .** {H12931} The
36240 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
36250 74 6f 63 6f 6d 6d 69 74 28 44 29 5d 20 69 6e 74  tocommit(D)] int
36260 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e  erface returns n
36270 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 20 20  on-zero or.**   
36280 20 20 20 20 20 20 20 7a 65 72 6f 20 69 66 20 74         zero if t
36290 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
362a0 6e 65 63 74 69 6f 6e 5d 20 44 20 69 73 20 6f 72  nection] D is or
362b0 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63   is not in autoc
362c0 6f 6d 6d 69 74 0a 2a 2a 20 20 20 20 20 20 20 20  ommit.**        
362d0 20 20 6d 6f 64 65 2c 20 72 65 73 70 65 63 74 69    mode, respecti
362e0 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  vely..**.** {H12
362f0 39 33 32 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20  932} Autocommit 
36300 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65  mode is on by de
36310 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  fault..**.** {H1
36320 32 39 33 33 7d 20 41 75 74 6f 63 6f 6d 6d 69 74  2933} Autocommit
36330 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65   mode is disable
36340 64 20 62 79 20 61 20 73 75 63 63 65 73 73 66 75  d by a successfu
36350 6c 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d  l [BEGIN] statem
36360 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ent..**.** {H129
36370 33 34 7d 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  34} Autocommit m
36380 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62  ode is enabled b
36390 79 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 5b  y a successful [
363a0 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c  COMMIT] or [ROLL
363b0 42 41 43 4b 5d 0a 2a 2a 20 20 20 20 20 20 20 20  BACK].**        
363c0 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a    statement..**.
363d0 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
363e0 2a 2a 0a 2a 2a 20 7b 41 31 32 39 33 36 7d 20 49  **.** {A12936} I
363f0 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  f another thread
36400 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74   changes the aut
36410 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f  ocommit status o
36420 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
36430 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 6e 65  *          conne
36440 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73  ction while this
36450 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e   routine is runn
36460 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
36470 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 20 20  turn value.**   
36480 20 20 20 20 20 20 20 69 73 20 75 6e 64 65 66 69         is undefi
36490 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
364a0 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
364b0 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  it(sqlite3*);../
364c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
364d0 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65  ind The Database
364e0 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65   Handle Of A Pre
364f0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
36500 7b 48 31 33 31 32 30 7d 20 3c 53 36 30 36 30 30  {H13120} <S60600
36510 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
36520 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e  te3_db_handle in
36530 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
36540 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
36550 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
36560 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b  .** to which a [
36570 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
36580 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 54 68  nt] belongs.  Th
36590 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  e database handl
365a0 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  e returned by.**
365b0 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
365c0 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 64  le is the same d
365d0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 74  atabase handle t
365e0 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73  hat was the firs
365f0 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
36600 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
36610 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c  epare_v2()] call
36620 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74   (or its variant
36630 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64  s) that was used
36640 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68   to.** create th
36650 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  e statement in t
36660 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a  he first place..
36670 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
36680 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 32 33 7d  :.**.** {H13123}
36690 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   The [sqlite3_db
366a0 5f 68 61 6e 64 6c 65 28 53 29 5d 20 69 6e 74 65  _handle(S)] inte
366b0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
366c0 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20  pointer.**      
366d0 20 20 20 20 74 6f 20 74 68 65 20 5b 64 61 74 61      to the [data
366e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
366f0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
36700 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
36710 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
36720 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71 6c 69  ment] S..*/.sqli
36730 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f  te3 *sqlite3_db_
36740 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73  handle(sqlite3_s
36750 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
36760 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65  PI3REF: Find the
36770 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73   next prepared s
36780 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31 34 30  tatement {H13140
36790 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60600>.**.**
367a0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
367b0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
367c0 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70  r to the next [p
367d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
367e0 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d  t] after.** pStm
367f0 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
36800 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
36810 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e  connection] pDb.
36820 20 20 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55    If pStmt is NU
36830 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  LL.** then this 
36840 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
36850 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
36860 68 65 20 66 69 72 73 74 20 70 72 65 70 61 72 65  he first prepare
36870 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61  d statement.** a
36880 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
36890 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
368a0 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 49 66 20  ection pDb.  If 
368b0 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74  no prepared stat
368c0 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69  ement.** satisfi
368d0 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e  es the condition
368e0 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
368f0 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55  e, it returns NU
36900 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  LL..**.** INVARI
36910 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
36920 31 34 33 7d 20 49 66 20 44 20 69 73 20 61 20 5b  143} If D is a [
36930 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36940 69 6f 6e 5d 20 74 68 61 74 20 68 6f 6c 64 73 20  ion] that holds 
36950 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20  one or more.**  
36960 20 20 20 20 20 20 20 20 75 6e 66 69 6e 61 6c 69          unfinali
36970 7a 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  zed [prepared st
36980 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53 20  atements] and S 
36990 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
369a0 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  r,.**          t
369b0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  hen [sqlite3_nex
369c0 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f  t_stmt(D, S)] ro
369d0 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75  utine shall retu
369e0 72 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  rn a pointer.** 
369f0 20 20 20 20 20 20 20 20 20 74 6f 20 6f 6e 65 20           to one 
36a00 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20  of the prepared 
36a10 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63  statements assoc
36a20 69 61 74 65 64 20 77 69 74 68 20 44 2e 0a 2a 2a  iated with D..**
36a30 0a 2a 2a 20 7b 48 31 33 31 34 36 7d 20 49 66 20  .** {H13146} If 
36a40 44 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  D is a [database
36a50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
36a60 74 20 68 6f 6c 64 73 20 6e 6f 20 75 6e 66 69 6e  t holds no unfin
36a70 61 6c 69 7a 65 64 0a 2a 2a 20 20 20 20 20 20 20  alized.**       
36a80 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
36a90 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53 20 69  tements] and S i
36aa0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
36ab0 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
36ac0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74     [sqlite3_next
36ad0 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75  _stmt(D, S)] rou
36ae0 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72  tine shall retur
36af0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
36b00 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 39 7d  ..**.** {H13149}
36b10 20 49 66 20 53 20 69 73 20 61 20 5b 70 72 65 70   If S is a [prep
36b20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
36b30 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  in the [database
36b40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
36b50 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 53  *          and S
36b60 20 69 73 20 6e 6f 74 20 74 68 65 20 6c 61 73 74   is not the last
36b70 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
36b80 65 6e 74 20 69 6e 20 44 2c 20 74 68 65 6e 0a 2a  ent in D, then.*
36b90 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
36ba0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c  te3_next_stmt(D,
36bb0 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61   S)] routine sha
36bc0 6c 6c 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e  ll return a poin
36bd0 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
36be0 74 6f 20 74 68 65 20 6e 65 78 74 20 70 72 65 70  to the next prep
36bf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
36c00 6e 20 44 20 61 66 74 65 72 20 53 2e 0a 2a 2a 0a  n D after S..**.
36c10 2a 2a 20 7b 48 31 33 31 35 32 7d 20 49 66 20 53  ** {H13152} If S
36c20 20 69 73 20 74 68 65 20 6c 61 73 74 20 5b 70 72   is the last [pr
36c30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
36c40 5d 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  ] in the.**     
36c50 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
36c60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 68 65  onnection] D the
36c70 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6e  n the [sqlite3_n
36c80 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 0a  ext_stmt(D, S)].
36c90 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74  **          rout
36ca0 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  ine shall return
36cb0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
36cc0 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f  .**.** ASSUMPTIO
36cd0 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 31 35  NS:.**.** {A1315
36ce0 34 7d 20 54 68 65 20 5b 64 61 74 61 62 61 73 65  4} The [database
36cf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69   connection] poi
36d00 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c  nter D in a call
36d10 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
36d20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
36d30 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65  mt(D,S)] must re
36d40 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64  fer to an open d
36d50 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20  atabase.**      
36d60 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61      connection a
36d70 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  nd in particular
36d80 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e   must not be a N
36d90 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a  ULL pointer..*/.
36da0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71  sqlite3_stmt *sq
36db0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
36dc0 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71  sqlite3 *pDb, sq
36dd0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
36de0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
36df0 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20  REF: Commit And 
36e00 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63  Rollback Notific
36e10 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20  ation Callbacks 
36e20 7b 48 31 32 39 35 30 7d 20 3c 53 36 30 34 30 30  {H12950} <S60400
36e30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
36e40 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
36e50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
36e60 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
36e70 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
36e80 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
36e90 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
36ea0 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a  n is committed..
36eb0 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  ** Any callback 
36ec0 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
36ed0 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
36ee0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a  3_commit_hook().
36ef0 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
36f00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36f10 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
36f20 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  n..** The sqlite
36f30 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
36f40 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
36f50 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
36f60 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
36f70 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
36f80 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
36f90 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2e 0a  n is committed..
36fa0 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  ** Any callback 
36fb0 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
36fc0 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
36fd0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a  3_commit_hook().
36fe0 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
36ff0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37000 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
37010 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67 20 61  n..** The pArg a
37020 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65  rgument is passe
37030 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
37040 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 49 66   callback..** If
37050 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e   the callback on
37060 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66   a commit hook f
37070 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
37080 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65  non-zero,.** the
37090 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20  n the commit is 
370a0 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
370b0 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
370c0 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75 6e 63   If another func
370d0 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69 6f 75  tion was previou
370e0 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 2c 20  sly registered, 
370f0 69 74 73 0a 2a 2a 20 70 41 72 67 20 76 61 6c 75  its.** pArg valu
37100 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
37110 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c 20 69  Otherwise NULL i
37120 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
37130 2a 20 52 65 67 69 73 74 65 72 69 6e 67 20 61 20  * Registering a 
37140 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69  NULL function di
37150 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62  sables the callb
37160 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74  ack..**.** For t
37170 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
37180 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73  his API, a trans
37190 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74  action is said t
371a0 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72  o have been.** r
371b0 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e  olled back if an
371c0 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42   explicit "ROLLB
371d0 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69  ACK" statement i
371e0 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a  s executed, or.*
371f0 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f  * an error or co
37200 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20  nstraint causes 
37210 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c  an implicit roll
37220 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a  back to occur..*
37230 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63  * The rollback c
37240 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69  allback is not i
37250 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e  nvoked if a tran
37260 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75  saction is.** au
37270 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
37280 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20  ed back because 
37290 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
372a0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
372b0 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61  d..** The rollba
372c0 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ck callback is n
372d0 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20  ot invoked if a 
372e0 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a  transaction is.*
372f0 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65  * rolled back be
37300 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20 63  cause a commit c
37310 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65 64  allback returned
37320 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74   non-zero..** <t
37330 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20 74 68  odo> Check on th
37340 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  is </todo>.**.**
37350 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
37360 2a 2a 20 7b 48 31 32 39 35 31 7d 20 54 68 65 20  ** {H12951} The 
37370 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
37380 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
37390 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
373a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
373b0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
373c0 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on F to be invok
373d0 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
373e0 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20   P whenever.**  
373f0 20 20 20 20 20 20 20 20 61 20 74 72 61 6e 73 61          a transa
37400 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 20 6f 6e  ction commits on
37410 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
37420 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
37430 0a 2a 2a 20 7b 48 31 32 39 35 32 7d 20 54 68 65  .** {H12952} The
37440 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   [sqlite3_commit
37450 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e  _hook(D,F,P)] in
37460 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
37470 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 0a 2a  the P argument.*
37480 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20  *          from 
37490 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
374a0 6c 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  l with the same 
374b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
374c0 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20 20  tion] D,.**     
374d0 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20       or NULL on 
374e0 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66  the first call f
374f0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
37500 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37510 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ion D..**.** {H1
37520 32 39 35 33 7d 20 45 61 63 68 20 63 61 6c 6c 20  2953} Each call 
37530 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  to [sqlite3_comm
37540 69 74 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65 72 77  it_hook()] overw
37550 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c 62 61  rites the callba
37560 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ck.**          r
37570 65 67 69 73 74 65 72 65 64 20 62 79 20 70 72 69  egistered by pri
37580 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20  or calls..**.** 
37590 7b 48 31 32 39 35 34 7d 20 49 66 20 74 68 65 20  {H12954} If the 
375a0 46 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  F argument to [s
375b0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
375c0 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55  ok(D,F,P)] is NU
375d0 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  LL.**          t
375e0 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  hen the commit h
375f0 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ook callback is 
37600 63 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20  canceled and no 
37610 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
37620 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20       is invoked 
37630 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63 74 69  when a transacti
37640 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a 2a 2a 0a 2a  on commits..**.*
37650 2a 20 7b 48 31 32 39 35 35 7d 20 49 66 20 74 68  * {H12955} If th
37660 65 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63  e commit callbac
37670 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
37680 72 6f 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d  ro then the comm
37690 69 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  it is.**        
376a0 20 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f    converted into
376b0 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a   a rollback..**.
376c0 2a 2a 20 7b 48 31 32 39 36 31 7d 20 54 68 65 20  ** {H12961} The 
376d0 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
376e0 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  k_hook(D,F,P)] i
376f0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
37700 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  rs the.**       
37710 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63     callback func
37720 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76  tion F to be inv
37730 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65  oked with argume
37740 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a  nt P whenever.**
37750 20 20 20 20 20 20 20 20 20 20 61 20 74 72 61 6e            a tran
37760 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20 62 61  saction rolls ba
37770 63 6b 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ck on the [datab
37780 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37790 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 32  D..**.** {H12962
377a0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
377b0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46  ollback_hook(D,F
377c0 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,P)] interface r
377d0 65 74 75 72 6e 73 20 74 68 65 20 50 0a 2a 2a 20  eturns the P.** 
377e0 20 20 20 20 20 20 20 20 20 61 72 67 75 6d 65 6e           argumen
377f0 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69  t from the previ
37800 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74 68  ous call with th
37810 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
37820 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
37830 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e  nection] D, or N
37840 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ULL on the first
37850 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20   call.**        
37860 20 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c    for a particul
37870 61 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ar database conn
37880 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20  ection D..**.** 
37890 7b 48 31 32 39 36 33 7d 20 45 61 63 68 20 63 61  {H12963} Each ca
378a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
378b0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 20  ollback_hook()] 
378c0 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 20 63  overwrites the c
378d0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  allback.**      
378e0 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 62      registered b
378f0 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a  y prior calls..*
37900 2a 0a 2a 2a 20 7b 48 31 32 39 36 34 7d 20 49 66  *.** {H12964} If
37910 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e 74 20   the F argument 
37920 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  to [sqlite3_roll
37930 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  back_hook(D,F,P)
37940 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20  ] is NULL.**    
37950 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 72        then the r
37960 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c  ollback hook cal
37970 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 65  lback is cancele
37980 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63  d and no callbac
37990 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  k.**          is
379a0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
379b0 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c  transaction roll
379c0 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76 6f 69 64 20  s back..*/.void 
379d0 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  *sqlite3_commit_
379e0 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69  hook(sqlite3*, i
379f0 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
37a00 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  id*);.void *sqli
37a10 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
37a20 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  k(sqlite3*, void
37a30 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69  (*)(void *), voi
37a40 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
37a50 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67  3REF: Data Chang
37a60 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  e Notification C
37a70 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 37 30  allbacks {H12970
37a80 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60400>.**.**
37a90 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64   The sqlite3_upd
37aa0 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ate_hook() inter
37ab0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
37ac0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
37ad0 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
37ae0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37af0 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20  ion] identified 
37b00 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
37b10 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69  ument.** to be i
37b20 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
37b30 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  a row is updated
37b40 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
37b50 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61  leted..** Any ca
37b60 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
37b70 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
37b80 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
37b90 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
37ba0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37bb0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
37bc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
37bd0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  nd argument is a
37be0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
37bf0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f  function to invo
37c00 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77  ke when a.** row
37c10 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73   is updated, ins
37c20 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
37c30 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
37c40 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
37c50 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
37c60 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61  y of the third a
37c70 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71  rgument.** to sq
37c80 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
37c90 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  k()..** The seco
37ca0 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75  nd callback argu
37cb0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
37cc0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
37cd0 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c  [SQLITE_DELETE],
37ce0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
37cf0 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e  PDATE], dependin
37d00 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
37d10 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
37d20 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  he callback.** t
37d30 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
37d40 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66   The third and f
37d50 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20  ourth arguments 
37d60 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
37d70 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73  contain pointers
37d80 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
37d90 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61  ase and table na
37da0 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  me containing th
37db0 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a  e affected row..
37dc0 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  ** The final cal
37dd0 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
37de0 69 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  is the rowid of 
37df0 74 68 65 20 72 6f 77 2e 20 49 6e 20 74 68 65 20  the row. In the 
37e00 63 61 73 65 20 6f 66 0a 2a 2a 20 61 6e 20 75 70  case of.** an up
37e10 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68  date, this is th
37e20 65 20 72 6f 77 69 64 20 61 66 74 65 72 20 74 68  e rowid after th
37e30 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70  e update takes p
37e40 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lace..**.** The 
37e50 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e  update hook is n
37e60 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  ot invoked when 
37e70 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20  internal system 
37e80 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f  tables are.** mo
37e90 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c  dified (i.e. sql
37ea0 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73  ite_master and s
37eb0 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e  qlite_sequence).
37ec0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65  .**.** If anothe
37ed0 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70  r function was p
37ee0 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
37ef0 65 72 65 64 2c 20 69 74 73 20 70 41 72 67 20 76  ered, its pArg v
37f00 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74 75 72  alue.** is retur
37f10 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
37f20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
37f30 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
37f40 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37  TS:.**.** {H1297
37f50 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
37f60 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c  update_hook(D,F,
37f70 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61  P)] interface ca
37f80 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  uses the callbac
37f90 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75  k.**          fu
37fa0 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69  nction F to be i
37fb0 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 69 72 73  nvoked with firs
37fc0 74 20 70 61 72 61 6d 65 74 65 72 20 50 20 77 68  t parameter P wh
37fd0 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20  enever.**       
37fe0 20 20 20 61 20 74 61 62 6c 65 20 72 6f 77 20 69     a table row i
37ff0 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65  s modified, inse
38000 72 74 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64  rted, or deleted
38010 20 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   on.**          
38020 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
38030 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
38040 2a 2a 20 7b 48 31 32 39 37 33 7d 20 54 68 65 20  ** {H12973} The 
38050 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
38060 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74  hook(D,F,P)] int
38070 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
38080 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20  he value.**     
38090 20 20 20 20 20 6f 66 20 50 20 66 6f 72 20 74 68       of P for th
380a0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
380b0 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
380c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
380d0 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] D,.**         
380e0 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 20 74 68 65   or NULL for the
380f0 20 66 69 72 73 74 20 63 61 6c 6c 2e 0a 2a 2a 0a   first call..**.
38100 2a 2a 20 7b 48 31 32 39 37 35 7d 20 49 66 20 74  ** {H12975} If t
38110 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 63  he update hook c
38120 61 6c 6c 62 61 63 6b 20 46 20 69 6e 20 5b 73 71  allback F in [sq
38130 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
38140 6b 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20 20 20  k(D,F,P)].**    
38150 20 20 20 20 20 20 69 73 20 4e 55 4c 4c 20 74 68        is NULL th
38160 65 6e 20 74 68 65 20 6e 6f 20 75 70 64 61 74 65  en the no update
38170 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6d   callbacks are m
38180 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ade..**.** {H129
38190 37 37 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  77} Each call to
381a0 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   [sqlite3_update
381b0 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 6f 76  _hook(D,F,P)] ov
381c0 65 72 72 69 64 65 73 20 70 72 69 6f 72 20 63 61  errides prior ca
381d0 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lls.**          
381e0 74 6f 20 74 68 65 20 73 61 6d 65 20 69 6e 74 65  to the same inte
381f0 72 66 61 63 65 20 6f 6e 20 74 68 65 20 73 61 6d  rface on the sam
38200 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
38210 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
38220 20 7b 48 31 32 39 37 39 7d 20 54 68 65 20 75 70   {H12979} The up
38230 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c 62 61  date hook callba
38240 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ck is not invoke
38250 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20  d when internal 
38260 73 79 73 74 65 6d 0a 2a 2a 20 20 20 20 20 20 20  system.**       
38270 20 20 20 74 61 62 6c 65 73 20 73 75 63 68 20 61     tables such a
38280 73 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20  s sqlite_master 
38290 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65  and sqlite_seque
382a0 6e 63 65 20 61 72 65 20 6d 6f 64 69 66 69 65 64  nce are modified
382b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 38 31 7d  ..**.** {H12981}
382c0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
382d0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 75 70 64  meter to the upd
382e0 61 74 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ate callback.** 
382f0 20 20 20 20 20 20 20 20 20 69 73 20 6f 6e 65 20           is one 
38300 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52  of [SQLITE_INSER
38310 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45  T], [SQLITE_DELE
38320 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  TE] or [SQLITE_U
38330 50 44 41 54 45 5d 2c 0a 2a 2a 20 20 20 20 20 20  PDATE],.**      
38340 20 20 20 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e      depending on
38350 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74   the operation t
38360 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63  hat caused the c
38370 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 69 6e  allback to be in
38380 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  voked..**.** {H1
38390 32 39 38 33 7d 20 54 68 65 20 74 68 69 72 64 20  2983} The third 
383a0 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d  and fourth argum
383b0 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ents to the call
383c0 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69  back contain poi
383d0 6e 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  nters.**        
383e0 20 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e    to zero-termin
383f0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
38400 67 73 20 77 68 69 63 68 20 61 72 65 20 74 68 65  gs which are the
38410 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
38420 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61            databa
38430 73 65 20 61 6e 64 20 74 61 62 6c 65 20 74 68 61  se and table tha
38440 74 20 69 73 20 62 65 69 6e 67 20 75 70 64 61 74  t is being updat
38450 65 64 2e 0a 0a 2a 2a 20 7b 48 31 32 39 38 35 7d  ed...** {H12985}
38460 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62   The final callb
38470 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ack parameter is
38480 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
38490 65 20 72 6f 77 20 61 66 74 65 72 0a 2a 2a 20 20  e row after.**  
384a0 20 20 20 20 20 20 20 20 74 68 65 20 63 68 61 6e          the chan
384b0 67 65 20 6f 63 63 75 72 73 2e 0a 2a 2f 0a 76 6f  ge occurs..*/.vo
384c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61  id *sqlite3_upda
384d0 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74  te_hook(.  sqlit
384e0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  e3*, .  void(*)(
384f0 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72  void *,int ,char
38500 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f   const *,char co
38510 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  nst *,sqlite3_in
38520 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b  t64),.  void*.);
38530 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38540 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
38550 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72  ble Shared Pager
38560 20 43 61 63 68 65 20 7b 48 31 30 33 33 30 7d 20   Cache {H10330} 
38570 3c 53 33 30 39 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S30900>.** KEYW
38580 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63 61  ORDS: {shared ca
38590 63 68 65 7d 20 7b 73 68 61 72 65 64 20 63 61 63  che} {shared cac
385a0 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54  he mode}.**.** T
385b0 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  his routine enab
385c0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
385d0 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74  the sharing of t
385e0 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68  he database cach
385f0 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20  e.** and schema 
38600 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
38610 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73  between [databas
38620 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63  e connection | c
38630 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74  onnections].** t
38640 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
38650 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20  ase. Sharing is 
38660 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  enabled if the a
38670 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a  rgument is true.
38680 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20  ** and disabled 
38690 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  if the argument 
386a0 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20  is false..**.** 
386b0 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 73  Cache sharing is
386c0 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73   enabled and dis
386d0 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e 74  abled for an ent
386e0 69 72 65 20 70 72 6f 63 65 73 73 2e 20 7b 45 4e  ire process. {EN
386f0 44 7d 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  D}.** This is a 
38700 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c  change as of SQL
38710 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
38720 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73  0. In prior vers
38730 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a  ions of SQLite,.
38740 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65  ** sharing was e
38750 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
38760 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65  ed for each thre
38770 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  ad separately..*
38780 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65 20 73  *.** The cache s
38790 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20  haring mode set 
387a0 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  by this interfac
387b0 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75  e effects all su
387c0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
387d0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  s to [sqlite3_op
387e0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
387f0 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
38800 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
38810 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  )]..** Existing 
38820 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
38830 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73  ions continue us
38840 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  e the sharing mo
38850 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69  de.** that was i
38860 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20  n effect at the 
38870 74 69 6d 65 20 74