/ Hex Artifact Content
Login

Artifact c1afc4a05dde8c6b9c8ea783b0b5a624892e299b:


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 32 20 32 30 30 38 2f 30  n,v 1.382 2008/0
05f0: 37 2f 32 38 20 31 39 3a 33 34 3a 35 33 20 64 72  7/28 19:34:53 dr
0600: 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e 64  h Exp $.*/.#ifnd
0610: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ef _SQLITE3_H_.#
0620: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f  define _SQLITE3_
0630: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64  H_.#include <std
0640: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65  arg.h>     /* Ne
0650: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66  eded for the def
0660: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69  inition of va_li
0670: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  st */../*.** Mak
0680: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61  e sure we can ca
0690: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72  ll this stuff fr
06a0: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65  om C++..*/.#ifde
06b0: 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78  f __cplusplus.ex
06c0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69  tern "C" {.#endi
06d0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68  f.../*.** Add th
06e0: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65  e ability to ove
06f0: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a  rride 'extern'.*
0700: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
0710: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65  _EXTERN.# define
0720: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65   SQLITE_EXTERN e
0730: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  xtern.#endif../*
0740: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0750: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0760: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0770: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0780: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0790: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
07a0: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
07b0: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
07c0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
07d0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
07e0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
07f0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0800: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0810: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0820: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0830: 75 6d 62 65 72 73 20 7b 48 31 30 30 31 30 7d 20  umbers {H10010} 
0840: 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60100>.**.** T
0850: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0860: 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f 56 45 52  N and SQLITE_VER
0870: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 64 65 66  SION_NUMBER #def
0880: 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68 65 20 73  ines in.** the s
0890: 71 6c 69 74 65 33 2e 68 20 66 69 6c 65 20 73 70  qlite3.h file sp
08a0: 65 63 69 66 79 20 74 68 65 20 76 65 72 73 69 6f  ecify the versio
08b0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 77 69 74 68  n of SQLite with
08c0: 20 77 68 69 63 68 0a 2a 2a 20 74 68 61 74 20 68   which.** that h
08d0: 65 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73  eader file is as
08e0: 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  sociated..**.** 
08f0: 54 68 65 20 22 76 65 72 73 69 6f 6e 22 20 6f 66  The "version" of
0900: 20 53 51 4c 69 74 65 20 69 73 20 61 20 73 74 72   SQLite is a str
0910: 69 6e 67 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ing of the form 
0920: 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54 68 65 20  "X.Y.Z"..** The 
0930: 70 68 72 61 73 65 20 22 61 6c 70 68 61 22 20 6f  phrase "alpha" o
0940: 72 20 22 62 65 74 61 22 20 6d 69 67 68 74 20 62  r "beta" might b
0950: 65 20 61 70 70 65 6e 64 65 64 20 61 66 74 65 72  e appended after
0960: 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68 65 20 58   the Z..** The X
0970: 20 76 61 6c 75 65 20 69 73 20 6d 61 6a 6f 72 20   value is major 
0980: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0990: 6c 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69 74  lways 3 in SQLit
09a0: 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c  e3..** The X val
09b0: 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20  ue only changes 
09c0: 77 68 65 6e 20 62 61 63 6b 77 61 72 64 73 20 63  when backwards c
09d0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73 0a  ompatibility is.
09e0: 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77 65  ** broken and we
09f0: 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65 72   intend to never
0a00: 20 62 72 65 61 6b 20 62 61 63 6b 77 61 72 64 73   break backwards
0a10: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
0a20: 2a 2a 20 54 68 65 20 59 20 76 61 6c 75 65 20 69  ** The Y value i
0a30: 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73  s the minor vers
0a40: 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 6f  ion number and o
0a50: 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 6e  nly changes when
0a60: 0a 2a 2a 20 74 68 65 72 65 20 61 72 65 20 6d 61  .** there are ma
0a70: 6a 6f 72 20 66 65 61 74 75 72 65 20 65 6e 68 61  jor feature enha
0a80: 6e 63 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72  ncements that ar
0a90: 65 20 66 6f 72 77 61 72 64 73 20 63 6f 6d 70 61  e forwards compa
0aa0: 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e 6f 74  tible.** but not
0ab0: 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
0ac0: 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 5a 20  tible..** The Z 
0ad0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 72 65 6c  value is the rel
0ae0: 65 61 73 65 20 6e 75 6d 62 65 72 20 61 6e 64 20  ease number and 
0af0: 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 77  is incremented w
0b00: 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 65 6c 65  ith.** each rele
0b10: 61 73 65 20 62 75 74 20 72 65 73 65 74 73 20 62  ase but resets b
0b20: 61 63 6b 20 74 6f 20 30 20 77 68 65 6e 65 76 65  ack to 0 wheneve
0b30: 72 20 59 20 69 73 20 69 6e 63 72 65 6d 65 6e 74  r Y is increment
0b40: 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ed..**.** See al
0b50: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
0b60: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
0b70: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
0b80: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e 0a 2a 2a  on_number()]..**
0b90: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
0ba0: 2a 2a 0a 2a 2a 20 7b 48 31 30 30 31 31 7d 20 54  **.** {H10011} T
0bb0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0bc0: 4e 20 23 64 65 66 69 6e 65 20 69 6e 20 74 68 65  N #define in the
0bd0: 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65   sqlite3.h heade
0be0: 72 20 66 69 6c 65 20 73 68 61 6c 6c 0a 2a 2a 20  r file shall.** 
0bf0: 20 20 20 20 20 20 20 20 20 65 76 61 6c 75 61 74           evaluat
0c00: 65 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  e to a string li
0c10: 74 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68  teral that is th
0c20: 65 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  e SQLite version
0c30: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
0c40: 68 20 77 68 69 63 68 20 74 68 65 20 68 65 61 64  h which the head
0c50: 65 72 20 66 69 6c 65 20 69 73 20 61 73 73 6f 63  er file is assoc
0c60: 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  iated..**.** {H1
0c70: 30 30 31 34 7d 20 54 68 65 20 53 51 4c 49 54 45  0014} The SQLITE
0c80: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0c90: 23 64 65 66 69 6e 65 20 73 68 61 6c 6c 20 72 65  #define shall re
0ca0: 73 6f 6c 76 65 20 74 6f 20 61 6e 20 69 6e 74 65  solve to an inte
0cb0: 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ger.**          
0cc0: 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20 28  with the value (
0cd0: 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30  X*1000000 + Y*10
0ce0: 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c  00 + Z) where X,
0cf0: 20 59 2c 20 61 6e 64 20 5a 0a 2a 2a 20 20 20 20   Y, and Z.**    
0d00: 20 20 20 20 20 20 61 72 65 20 74 68 65 20 6d 61        are the ma
0d10: 6a 6f 72 20 76 65 72 73 69 6f 6e 2c 20 6d 69 6e  jor version, min
0d20: 6f 72 20 76 65 72 73 69 6f 6e 2c 20 61 6e 64 20  or version, and 
0d30: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 0a  release number..
0d40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0d50: 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20  E_VERSION       
0d60: 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65    "--VERS--".#de
0d70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
0d80: 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 2d 2d 56 45  ION_NUMBER  --VE
0d90: 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 0a  RSION-NUMBER--..
0da0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
0db0: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
0dc0: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
0dd0: 20 7b 48 31 30 30 32 30 7d 20 3c 53 36 30 31 30   {H10020} <S6010
0de0: 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
0df0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a  sqlite3_version.
0e00: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 65 61 74  **.** These feat
0e10: 75 72 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  ures provide the
0e20: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
0e30: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
0e40: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 61 6e 64  _VERSION].** and
0e50: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0e60: 5f 4e 55 4d 42 45 52 5d 20 23 64 65 66 69 6e 65  _NUMBER] #define
0e70: 73 20 69 6e 20 74 68 65 20 68 65 61 64 65 72 2c  s in the header,
0e80: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
0e90: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
0ea0: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
0eb0: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
0ec0: 6c 65 2e 20 20 43 61 75 74 69 6f 75 73 20 70 72  le.  Cautious pr
0ed0: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 0a  ogrammers might.
0ee0: 2a 2a 20 69 6e 63 6c 75 64 65 20 61 20 63 68 65  ** include a che
0ef0: 63 6b 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c  ck in their appl
0f00: 69 63 61 74 69 6f 6e 20 74 6f 20 76 65 72 69 66  ication to verif
0f10: 79 20 74 68 61 74 0a 2a 2a 20 73 71 6c 69 74 65  y that.** sqlite
0f20: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
0f30: 62 65 72 28 29 20 61 6c 77 61 79 73 20 72 65 74  ber() always ret
0f40: 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 0a 2a  urns the value.*
0f50: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  * [SQLITE_VERSIO
0f60: 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a  N_NUMBER]..**.**
0f70: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62   The sqlite3_lib
0f80: 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69  version() functi
0f90: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  on returns the s
0fa0: 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
0fb0: 61 73 20 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20  as is.** in the 
0fc0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
0fd0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
0fe0: 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e  t.  The function
0ff0: 20 69 73 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20   is provided.** 
1000: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
1010: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
1020: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
1030: 61 76 65 20 64 69 72 65 63 74 20 61 63 63 65 73  ave direct acces
1040: 73 20 74 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63  s to string.** c
1050: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
1060: 74 68 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49  the DLL..**.** I
1070: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1080: 20 7b 48 31 30 30 32 31 7d 20 54 68 65 20 5b 73   {H10021} The [s
1090: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
10a0: 6e 5f 6e 75 6d 62 65 72 28 29 5d 20 69 6e 74 65  n_number()] inte
10b0: 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75  rface shall retu
10c0: 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  rn.**          a
10d0: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
10e0: 74 6f 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  to [SQLITE_VERSI
10f0: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a  ON_NUMBER]..**.*
1100: 2a 20 7b 48 31 30 30 32 32 7d 20 54 68 65 20 5b  * {H10022} The [
1110: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5d  sqlite3_version]
1120: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1130: 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 0a 2a   shall contain.*
1140: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 74  *          the t
1150: 65 78 74 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ext of the [SQLI
1160: 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73 74 72 69  TE_VERSION] stri
1170: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32  ng..**.** {H1002
1180: 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
1190: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 66 75  libversion()] fu
11a0: 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74  nction shall ret
11b0: 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
11c0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
11d0: 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f   [sqlite3_versio
11e0: 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  n] string consta
11f0: 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  nt..*/.SQLITE_EX
1200: 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20  TERN const char 
1210: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
1220: 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  ];.const char *s
1230: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1240: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
1250: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1260: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1280: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1290: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
12a0: 65 61 64 73 61 66 65 20 7b 48 31 30 31 30 30 7d  eadsafe {H10100}
12b0: 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S60100>.**.** 
12c0: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f  SQLite can be co
12d0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77  mpiled with or w
12e0: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20  ithout mutexes. 
12f0: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51   When.** the [SQ
1300: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1310: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1320: 6d 61 63 72 6f 20 69 73 20 74 72 75 65 2c 20 6d  macro is true, m
1330: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
1340: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
1350: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
1360: 20 57 68 65 6e 20 74 68 61 74 20 6d 61 63 72 6f   When that macro
1370: 20 69 73 20 66 61 6c 73 65 2c 0a 2a 2a 20 74 68   is false,.** th
1380: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1390: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
13a0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
13b0: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
13c0: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
13d0: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
13e0: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
13f0: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
1400: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
1410: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
1420: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
1430: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
1440: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
1450: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
1460: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
1470: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
1480: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
1490: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
14a0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
14b0: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68  e enabled..** Th
14c0: 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  e default behavi
14d0: 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65  or is for mutexe
14e0: 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e  s to be enabled.
14f0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1500: 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
1510: 64 20 62 79 20 61 20 70 72 6f 67 72 61 6d 20 74  d by a program t
1520: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
1530: 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20   the.** version 
1540: 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69  of SQLite that i
1550: 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61  t is linking aga
1560: 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65  inst was compile
1570: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65  d with.** the de
1580: 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66  sired setting of
1590: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
15a0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a  EADSAFE] macro..
15b0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
15c0: 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74  face only report
15d0: 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  s on the compile
15e0: 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74  -time mutex sett
15f0: 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53  ing.** of the [S
1600: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1610: 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69  ] flag.  If SQLi
1620: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
1630: 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48  ith.** SQLITE_TH
1640: 52 45 41 44 53 41 46 45 3d 31 20 74 68 65 6e 20  READSAFE=1 then 
1650: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62  mutexes are enab
1660: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62  led by default b
1670: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c  ut.** can be ful
1680: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20  ly or partially 
1690: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61  disabled using a
16a0: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
16b0: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77  3_config()].** w
16c0: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53  ith the verbs [S
16d0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
16e0: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c  GLETHREAD], [SQL
16f0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
1700: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b  THREAD],.** or [
1710: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
1720: 54 45 58 5d 2e 20 20 54 68 65 20 72 65 74 75 72  TEX].  The retur
1730: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
1740: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 0a 2a  function shows.*
1750: 2a 20 6f 6e 6c 79 20 74 68 65 20 64 65 66 61 75  * only the defau
1760: 6c 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  lt compile-time 
1770: 73 65 74 74 69 6e 67 2c 20 6e 6f 74 20 61 6e 79  setting, not any
1780: 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65   run-time change
1790: 73 0a 2a 2a 20 74 6f 20 74 68 61 74 20 73 65 74  s.** to that set
17a0: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ting..**.** INVA
17b0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
17c0: 31 30 31 30 31 7d 20 54 68 65 20 5b 73 71 6c 69  10101} The [sqli
17d0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
17e0: 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c  ] function shall
17f0: 20 72 65 74 75 72 6e 20 6e 6f 6e 7a 65 72 6f 20   return nonzero 
1800: 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  if.**          S
1810: 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c  QLite was compil
1820: 65 64 20 77 69 74 68 20 74 68 65 20 69 74 73 20  ed with the its 
1830: 6d 75 74 65 78 65 73 20 65 6e 61 62 6c 65 64 20  mutexes enabled 
1840: 62 79 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20  by default.**   
1850: 20 20 20 20 20 20 20 6f 72 20 7a 65 72 6f 20 69         or zero i
1860: 66 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d  f SQLite was com
1870: 70 69 6c 65 64 20 73 75 63 68 20 74 68 61 74 20  piled such that 
1880: 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 20  mutexes are.**  
1890: 20 20 20 20 20 20 20 20 70 65 72 6d 61 6e 65 6e          permanen
18a0: 74 6c 79 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  tly disabled..**
18b0: 0a 2a 2a 20 7b 48 31 30 31 30 32 7d 20 54 68 65  .** {H10102} The
18c0: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
18d0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
18e0: 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 66 75  threadsafe()] fu
18f0: 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  nction.**       
1900: 20 20 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68 61     shall not cha
1910: 6e 67 65 20 77 68 65 6e 20 6d 75 74 65 78 20 73  nge when mutex s
1920: 65 74 74 69 6e 67 20 61 72 65 20 6d 6f 64 69 66  etting are modif
1930: 69 65 64 20 61 74 0a 2a 2a 20 20 20 20 20 20 20  ied at.**       
1940: 20 20 20 72 75 6e 74 69 6d 65 20 75 73 69 6e 67     runtime using
1950: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
1960: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
1970: 65 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20  e and .**       
1980: 20 20 20 65 73 70 65 63 69 61 6c 6c 79 20 74 68     especially th
1990: 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
19a0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 0a  _SINGLETHREAD],.
19b0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
19c0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
19d0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
19e0: 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
19f0: 45 44 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ED],.**         
1a00: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
1a10: 46 49 47 5f 4d 55 54 45 58 5d 20 76 65 72 62 73  FIG_MUTEX] verbs
1a20: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1a30: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
1a40: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a50: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
1a60: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b  nection Handle {
1a70: 48 31 32 30 30 30 7d 20 3c 53 34 30 32 30 30 3e  H12000} <S40200>
1a80: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
1a90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1aa0: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
1ab0: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
1ac0: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
1ad0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
1ae0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
1af0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
1b00: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
1b10: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
1b20: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
1b30: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
1b40: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
1b50: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
1b60: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
1b70: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
1b80: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1b90: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
1ba0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
1bb0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
1bc0: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
1bd0: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
1be0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
1bf0: 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f  is its destructo
1c00: 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  r.  There are ma
1c10: 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61  ny other interfa
1c20: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
1c30: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1c40: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
1c50: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
1c60: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1c70: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1c80: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
1c90: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
1ca0: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
1cb0: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
1cc0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1cd0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
1ce0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
1cf0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
1d00: 65 67 65 72 20 54 79 70 65 73 20 7b 48 31 30 32  eger Types {H102
1d10: 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 2a 2a 20  00} <S10110>.** 
1d20: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
1d30: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
1d40: 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  nt64.**.** Becau
1d50: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63  se there is no c
1d60: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61  ross-platform wa
1d70: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d  y to specify 64-
1d80: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65  bit integer type
1d90: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c  s.** SQLite incl
1da0: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f  udes typedefs fo
1db0: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
1dc0: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
1dd0: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egers..**.** The
1de0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
1df0: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  nd sqlite3_uint6
1e00: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72  4 are the prefer
1e10: 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74  red type definit
1e20: 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  ions..** The sql
1e30: 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  ite_int64 and sq
1e40: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65  lite_uint64 type
1e50: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  s are supported 
1e60: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
1e70: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
1e80: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  nly..**.** INVAR
1e90: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
1ea0: 30 32 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  0201} The [sqlit
1eb0: 65 5f 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71  e_int64] and [sq
1ec0: 6c 69 74 65 33 5f 69 6e 74 36 34 5d 20 74 79 70  lite3_int64] typ
1ed0: 65 20 73 68 61 6c 6c 20 73 70 65 63 69 66 79 0a  e shall specify.
1ee0: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 36 34  **          a 64
1ef0: 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
1f00: 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32  ger..**.** {H102
1f10: 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f  02} The [sqlite_
1f20: 75 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c  uint64] and [sql
1f30: 69 74 65 33 5f 75 69 6e 74 36 34 5d 20 74 79 70  ite3_uint64] typ
1f40: 65 20 73 68 61 6c 6c 20 73 70 65 63 69 66 79 0a  e shall specify.
1f50: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 36 34  **          a 64
1f60: 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
1f70: 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66 64 65 66  teger..*/.#ifdef
1f80: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
1f90: 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c  PE.  typedef SQL
1fa0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
1fb0: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
1fc0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
1fd0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
1fe0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
1ff0: 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f  .#elif defined(_
2000: 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69  MSC_VER) || defi
2010: 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f  ned(__BORLANDC__
2020: 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e  ).  typedef __in
2030: 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  t64 sqlite_int64
2040: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
2050: 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c  gned __int64 sql
2060: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73  ite_uint64;.#els
2070: 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67  e.  typedef long
2080: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2090: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
20a0: 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20  f unsigned long 
20b0: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
20c0: 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74  uint64;.#endif.t
20d0: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e  ypedef sqlite_in
20e0: 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t64 sqlite3_int6
20f0: 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  4;.typedef sqlit
2100: 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e_uint64 sqlite3
2110: 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20  _uint64;../*.** 
2120: 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72  If compiling for
2130: 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61   a processor tha
2140: 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67  t lacks floating
2150: 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a   point support,.
2160: 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e  ** substitute in
2170: 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69  teger for floati
2180: 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66  ng-point..*/.#if
2190: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
21a0: 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23  FLOATING_POINT.#
21b0: 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73   define double s
21c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e  qlite3_int64.#en
21d0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
21e0: 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44  REF: Closing A D
21f0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2200: 6f 6e 20 7b 48 31 32 30 31 30 7d 20 3c 53 33 30  on {H12010} <S30
2210: 31 30 30 3e 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a  100><S40200>.**.
2220: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
2230: 69 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  is the destructo
2240: 72 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  r for the [sqlit
2250: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  e3] object..**.*
2260: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
2270: 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66  hould [sqlite3_f
2280: 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
2290: 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  ze] all [prepare
22a0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a  d statements].**
22b0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c   and [sqlite3_bl
22c0: 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65  ob_close | close
22d0: 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64  ] all [BLOB hand
22e0: 6c 65 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20  les] associated 
22f0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  with.** the [sql
2300: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69  ite3] object pri
2310: 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67  or to attempting
2320: 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62   to close the ob
2330: 6a 65 63 74 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  ject..** The [sq
2340: 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
2350: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  )] interface can
2360: 20 62 65 20 75 73 65 64 20 74 6f 20 6c 6f 63 61   be used to loca
2370: 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70 72 65 70 61  te all.** [prepa
2380: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
2390: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
23a0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
23b0: 65 63 74 69 6f 6e 5d 20 69 66 20 64 65 73 69 72  ection] if desir
23c0: 65 64 2e 0a 2a 2a 20 54 79 70 69 63 61 6c 20 63  ed..** Typical c
23d0: 6f 64 65 20 6d 69 67 68 74 20 6c 6f 6f 6b 20 6c  ode might look l
23e0: 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
23f0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
2400: 3e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  >.** sqlite3_stm
2410: 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a 20 77 68 69  t *pStmt;.** whi
2420: 6c 65 28 20 28 70 53 74 6d 74 20 3d 20 73 71 6c  le( (pStmt = sql
2430: 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 64  ite3_next_stmt(d
2440: 62 2c 20 30 29 29 21 3d 30 20 29 7b 0a 2a 2a 20  b, 0))!=0 ){.** 
2450: 26 6e 62 73 70 3b 20 20 20 73 71 6c 69 74 65 33  &nbsp;   sqlite3
2460: 5f 66 69 6e 61 6c 69 7a 65 28 70 53 74 6d 74 29  _finalize(pStmt)
2470: 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f 70 72 65 3e  ;.** }.** </pre>
2480: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
2490: 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
24a0: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
24b0: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
24c0: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
24d0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
24e0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
24f0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2500: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2510: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31  TS:.**.** {H1201
2520: 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  1} A successful 
2530: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2540: 5f 63 6c 6f 73 65 28 43 29 5d 20 73 68 61 6c 6c  _close(C)] shall
2550: 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20   destroy the.** 
2560: 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
2570: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
2580: 62 6a 65 63 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b  bject C..**.** {
2590: 48 31 32 30 31 32 7d 20 41 20 73 75 63 63 65 73  H12012} A succes
25a0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
25b0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
25c0: 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c  shall return SQL
25d0: 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ITE_OK..**.** {H
25e0: 31 32 30 31 33 7d 20 41 20 73 75 63 63 65 73 73  12013} A success
25f0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
2600: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73  ite3_close(C)] s
2610: 68 61 6c 6c 20 72 65 6c 65 61 73 65 20 61 6c 6c  hall release all
2620: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d  .**          mem
2630: 6f 72 79 20 61 6e 64 20 73 79 73 74 65 6d 20 72  ory and system r
2640: 65 73 6f 75 72 63 65 73 20 61 73 73 6f 63 69 61  esources associa
2650: 74 65 64 20 77 69 74 68 20 5b 64 61 74 61 62 61  ted with [databa
2660: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
2670: 2a 20 20 20 20 20 20 20 20 20 20 43 2e 0a 2a 2a  *          C..**
2680: 0a 2a 2a 20 7b 48 31 32 30 31 34 7d 20 41 20 63  .** {H12014} A c
2690: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
26a0: 63 6c 6f 73 65 28 43 29 5d 20 6f 6e 20 61 20 5b  close(C)] on a [
26b0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26c0: 69 6f 6e 5d 20 43 20 74 68 61 74 0a 2a 2a 20 20  ion] C that.**  
26d0: 20 20 20 20 20 20 20 20 68 61 73 20 6f 6e 65 20          has one 
26e0: 6f 72 20 6d 6f 72 65 20 6f 70 65 6e 20 5b 70 72  or more open [pr
26f0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2700: 73 5d 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69  s] shall fail wi
2710: 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  th.**          a
2720: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
2730: 65 72 72 6f 72 20 63 6f 64 65 2e 0a 2a 2a 0a 2a  error code..**.*
2740: 2a 20 7b 48 31 32 30 31 35 7d 20 41 20 63 61 6c  * {H12015} A cal
2750: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  l to [sqlite3_cl
2760: 6f 73 65 28 43 29 5d 20 77 68 65 72 65 20 43 20  ose(C)] where C 
2770: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2780: 72 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  r shall.**      
2790: 20 20 20 20 72 65 74 75 72 6e 20 53 51 4c 49 54      return SQLIT
27a0: 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  E_OK..**.** {H12
27b0: 30 31 39 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74  019} When [sqlit
27c0: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 69 73 20  e3_close(C)] is 
27d0: 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 5b 64 61  invoked on a [da
27e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
27f0: 6e 5d 20 43 0a 2a 2a 20 20 20 20 20 20 20 20 20  n] C.**         
2800: 20 74 68 61 74 20 68 61 73 20 61 20 70 65 6e 64   that has a pend
2810: 69 6e 67 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  ing transaction,
2820: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
2830: 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20   shall be.**    
2840: 20 20 20 20 20 20 72 6f 6c 6c 65 64 20 62 61 63        rolled bac
2850: 6b 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54  k..**.** ASSUMPT
2860: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  IONS:.**.** {A12
2870: 30 31 36 7d 20 54 68 65 20 43 20 70 61 72 61 6d  016} The C param
2880: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2890: 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75 73 74 20  _close(C)] must 
28a0: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
28b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69  .**          poi
28c0: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  nter or an [sqli
28d0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  te3] object poin
28e0: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ter obtained.** 
28f0: 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 5b 73           from [s
2900: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2910: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2920: 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
2930: 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
2940: 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20  _v2()], and not 
2950: 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65  previously close
2960: 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2970: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20  3_close(sqlite3 
2980: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
2990: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
29a0: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
29b0: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
29c0: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
29d0: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
29e0: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
29f0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
2a00: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
2a10: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
2a20: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
2a30: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
2a40: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
2a50: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2a60: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
2a70: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
2a80: 74 65 72 66 61 63 65 20 7b 48 31 32 31 30 30 7d  terface {H12100}
2a90: 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10000>.**.** 
2aa0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
2ab0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2ac0: 61 20 63 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79  a convenient way
2ad0: 20 6f 66 20 72 75 6e 6e 69 6e 67 20 6f 6e 65 20   of running one 
2ae0: 6f 72 20 6d 6f 72 65 0a 2a 2a 20 53 51 4c 20 73  or more.** SQL s
2af0: 74 61 74 65 6d 65 6e 74 73 20 77 69 74 68 6f 75  tatements withou
2b00: 74 20 68 61 76 69 6e 67 20 74 6f 20 77 72 69 74  t having to writ
2b10: 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64  e a lot of C cod
2b20: 65 2e 20 20 54 68 65 20 55 54 46 2d 38 20 65 6e  e.  The UTF-8 en
2b30: 63 6f 64 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  coded.** SQL sta
2b40: 74 65 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73  tements are pass
2b50: 65 64 20 69 6e 20 61 73 20 74 68 65 20 73 65 63  ed in as the sec
2b60: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
2b70: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2e   sqlite3_exec().
2b80: 0a 2a 2a 20 54 68 65 20 73 74 61 74 65 6d 65 6e  .** The statemen
2b90: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
2ba0: 20 6f 6e 65 20 62 79 20 6f 6e 65 20 75 6e 74 69   one by one unti
2bb0: 6c 20 65 69 74 68 65 72 20 61 6e 20 65 72 72 6f  l either an erro
2bc0: 72 20 6f 72 0a 2a 2a 20 61 6e 20 69 6e 74 65 72  r or.** an inter
2bd0: 72 75 70 74 20 69 73 20 65 6e 63 6f 75 6e 74 65  rupt is encounte
2be0: 72 65 64 2c 20 6f 72 20 75 6e 74 69 6c 20 74 68  red, or until th
2bf0: 65 79 20 61 72 65 20 61 6c 6c 20 64 6f 6e 65 2e  ey are all done.
2c00: 20 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65    The 3rd parame
2c10: 74 65 72 0a 2a 2a 20 69 73 20 61 6e 20 6f 70 74  ter.** is an opt
2c20: 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 74  ional callback t
2c30: 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hat is invoked o
2c40: 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77  nce for each row
2c50: 20 6f 66 20 61 6e 79 20 71 75 65 72 79 0a 2a 2a   of any query.**
2c60: 20 72 65 73 75 6c 74 73 20 70 72 6f 64 75 63 65   results produce
2c70: 64 20 62 79 20 74 68 65 20 53 51 4c 20 73 74 61  d by the SQL sta
2c80: 74 65 6d 65 6e 74 73 2e 20 20 54 68 65 20 35 74  tements.  The 5t
2c90: 68 20 70 61 72 61 6d 65 74 65 72 20 74 65 6c 6c  h parameter tell
2ca0: 73 20 77 68 65 72 65 0a 2a 2a 20 74 6f 20 77 72  s where.** to wr
2cb0: 69 74 65 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  ite any error me
2cc0: 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ssages..**.** Th
2cd0: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
2ce0: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
2cf0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
2d00: 6d 65 74 65 72 20 69 73 20 68 65 6c 64 0a 2a 2a  meter is held.**
2d10: 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   in memory obtai
2d20: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2d30: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f  3_malloc()].  To
2d40: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20   avoid a memory 
2d50: 6c 65 61 6b 2c 0a 2a 2a 20 74 68 65 20 63 61 6c  leak,.** the cal
2d60: 6c 69 6e 67 20 61 70 70 6c 69 63 61 74 69 6f 6e  ling application
2d70: 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 5b 73 71   should call [sq
2d80: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
2d90: 20 61 6e 79 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   any error.** me
2da0: 73 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 74  ssage returned t
2db0: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
2dc0: 61 72 61 6d 65 74 65 72 20 77 68 65 6e 20 69 74  arameter when it
2dd0: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
2de0: 69 6e 67 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  ing.** the error
2df0: 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
2e00: 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2e10: 6d 65 6e 74 20 69 6e 20 74 68 65 20 32 6e 64 20  ment in the 2nd 
2e20: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
2e30: 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74  L or an empty st
2e40: 72 69 6e 67 0a 2a 2a 20 6f 72 20 61 20 73 74 72  ring.** or a str
2e50: 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6f  ing containing o
2e60: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61  nly whitespace a
2e70: 6e 64 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  nd comments, the
2e80: 6e 20 6e 6f 20 53 51 4c 0a 2a 2a 20 73 74 61 74  n no SQL.** stat
2e90: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75  ements are evalu
2ea0: 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74  ated and the dat
2eb0: 61 62 61 73 65 20 69 73 20 6e 6f 74 20 63 68 61  abase is not cha
2ec0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nged..**.** The 
2ed0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
2ee0: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
2ef0: 65 6d 65 6e 74 65 64 20 69 6e 20 74 65 72 6d 73  emented in terms
2f00: 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
2f10: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
2f20: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
2f30: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69   and [sqlite3_fi
2f40: 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68  nalize()]..** Th
2f50: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
2f60: 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
2f70: 74 68 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74  thing to the dat
2f80: 61 62 61 73 65 20 74 68 61 74 20 63 61 6e 6e 6f  abase that canno
2f90: 74 20 62 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20  t be done.** by 
2fa0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2fb0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2fc0: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
2fd0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2fe0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
2ff0: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
3000: 31 30 31 7d 20 41 20 73 75 63 63 65 73 73 66 75  101} A successfu
3010: 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
3020: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c  [sqlite3_exec(D,
3030: 53 2c 43 2c 41 2c 45 29 5d 0a 2a 2a 20 20 20 20  S,C,A,E)].**    
3040: 20 20 20 20 20 20 73 68 61 6c 6c 20 73 65 71 75        shall sequ
3050: 65 6e 74 69 61 6c 6c 79 20 65 76 61 6c 75 61 74  entially evaluat
3060: 65 20 61 6c 6c 20 6f 66 20 74 68 65 20 55 54 46  e all of the UTF
3070: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 20  -8 encoded,.**  
3080: 20 20 20 20 20 20 20 20 73 65 6d 69 63 6f 6c 6f          semicolo
3090: 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20  n-separated SQL 
30a0: 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
30b0: 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
30c0: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  d.**          st
30d0: 72 69 6e 67 20 53 20 77 69 74 68 69 6e 20 74 68  ring S within th
30e0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
30f0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
3100: 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
3110: 7b 48 31 32 31 30 32 7d 20 49 66 20 74 68 65 20  {H12102} If the 
3120: 53 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  S parameter to [
3130: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53  sqlite3_exec(D,S
3140: 2c 43 2c 41 2c 45 29 5d 20 69 73 20 4e 55 4c 4c  ,C,A,E)] is NULL
3150: 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
3160: 20 20 74 68 65 20 61 63 74 69 6f 6e 73 20 6f 66    the actions of
3170: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 73   the interface s
3180: 68 61 6c 6c 20 62 65 20 74 68 65 20 73 61 6d 65  hall be the same
3190: 20 61 73 20 69 66 20 74 68 65 0a 2a 2a 20 20 20   as if the.**   
31a0: 20 20 20 20 20 20 20 53 20 70 61 72 61 6d 65 74         S paramet
31b0: 65 72 20 77 65 72 65 20 61 6e 20 65 6d 70 74 79  er were an empty
31c0: 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
31d0: 48 31 32 31 30 34 7d 20 54 68 65 20 72 65 74 75  H12104} The retu
31e0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  rn value of [sql
31f0: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61  ite3_exec()] sha
3200: 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 4f 4b  ll be [SQLITE_OK
3210: 5d 20 69 66 20 61 6c 6c 0a 2a 2a 20 20 20 20 20  ] if all.**     
3220: 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65       SQL stateme
3230: 6e 74 73 20 72 75 6e 20 73 75 63 63 65 73 73 66  nts run successf
3240: 75 6c 6c 79 20 61 6e 64 20 74 6f 20 63 6f 6d 70  ully and to comp
3250: 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48  letion..**.** {H
3260: 31 32 31 30 35 7d 20 54 68 65 20 72 65 74 75 72  12105} The retur
3270: 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  n value of [sqli
3280: 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c  te3_exec()] shal
3290: 6c 20 62 65 20 61 6e 20 61 70 70 72 6f 70 72 69  l be an appropri
32a0: 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ate.**          
32b0: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
32c0: 63 6f 64 65 5d 20 69 66 20 61 6e 79 20 53 51 4c  code] if any SQL
32d0: 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 73   statement fails
32e0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 37 7d  ..**.** {H12107}
32f0: 20 49 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   If one or more 
3300: 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  of the SQL state
3310: 6d 65 6e 74 73 20 68 61 6e 64 65 64 20 74 6f 20  ments handed to 
3320: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3330: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
3340: 75 72 6e 20 72 65 73 75 6c 74 73 20 61 6e 64 20  urn results and 
3350: 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
3360: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  r is not NULL, t
3370: 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
3380: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
3390: 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20  ction specified 
33a0: 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  by the 3rd param
33b0: 65 74 65 72 20 73 68 61 6c 6c 20 62 65 0a 2a 2a  eter shall be.**
33c0: 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 6b 65            invoke
33d0: 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
33e0: 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 0a 2a  row of result..*
33f0: 2a 0a 2a 2a 20 7b 48 31 32 31 31 30 7d 20 49 66  *.** {H12110} If
3400: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
3410: 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
3420: 20 76 61 6c 75 65 20 74 68 65 6e 20 5b 73 71 6c   value then [sql
3430: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20  ite3_exec()].** 
3440: 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 61           shall a
3450: 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
3460: 74 65 6d 65 6e 74 20 69 74 20 69 73 20 63 75 72  tement it is cur
3470: 72 65 6e 74 6c 79 20 65 76 61 6c 75 61 74 69 6e  rently evaluatin
3480: 67 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  g,.**          s
3490: 6b 69 70 20 61 6c 6c 20 73 75 62 73 65 71 75 65  kip all subseque
34a0: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  nt SQL statement
34b0: 73 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  s, and return [S
34c0: 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a  QLITE_ABORT]..**
34d0: 0a 2a 2a 20 7b 48 31 32 31 31 33 7d 20 54 68 65  .** {H12113} The
34e0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
34f0: 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
3500: 70 61 73 73 20 69 74 73 20 34 74 68 20 70 61 72  pass its 4th par
3510: 61 6d 65 74 65 72 20 74 68 72 6f 75 67 68 0a 2a  ameter through.*
3520: 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68  *          as th
3530: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
3540: 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  of the callback.
3550: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 36 7d 20  .**.** {H12116} 
3560: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  The [sqlite3_exe
3570: 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61  c()] routine sha
3580: 6c 6c 20 73 65 74 20 74 68 65 20 32 6e 64 20 70  ll set the 2nd p
3590: 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a  arameter of its.
35a0: 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
35b0: 62 61 63 6b 20 74 6f 20 62 65 20 74 68 65 20 6e  back to be the n
35c0: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
35d0: 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
35e0: 72 6f 77 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  row of.**       
35f0: 20 20 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a     result..**.**
3600: 20 7b 48 31 32 31 31 39 7d 20 54 68 65 20 5b 73   {H12119} The [s
3610: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
3620: 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74  outine shall set
3630: 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
3640: 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20  er of its.**    
3650: 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74        callback t
3660: 6f 20 62 65 20 61 6e 20 61 72 72 61 79 20 6f 66  o be an array of
3670: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3680: 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65  ings holding the
3690: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
36a0: 75 65 73 20 66 6f 72 20 65 61 63 68 20 63 6f 6c  ues for each col
36b0: 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
36c0: 6e 74 20 72 65 73 75 6c 74 20 73 65 74 20 72 6f  nt result set ro
36d0: 77 20 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  w as.**         
36e0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
36f0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
3700: 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ext()]..**.** {H
3710: 31 32 31 32 32 7d 20 54 68 65 20 5b 73 71 6c 69  12122} The [sqli
3720: 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74  te3_exec()] rout
3730: 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68  ine shall set th
3740: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
3750: 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20  of its.**       
3760: 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62     callback to b
3770: 65 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  e an array of po
3780: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3790: 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a  s holding the.**
37a0: 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 73 20            names 
37b0: 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
37c0: 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72  s as obtained fr
37d0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
37e0: 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a  mn_name()]..**.*
37f0: 2a 20 7b 48 31 32 31 32 35 7d 20 49 66 20 74 68  * {H12125} If th
3800: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
3810: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
3820: 28 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ()] is NULL then
3830: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
3840: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68  lite3_exec()] sh
3850: 61 6c 6c 20 73 69 6c 65 6e 74 6c 79 20 64 69 73  all silently dis
3860: 63 61 72 64 20 71 75 65 72 79 20 72 65 73 75 6c  card query resul
3870: 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33  ts..**.** {H1213
3880: 31 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  1} If an error o
3890: 63 63 75 72 73 20 77 68 69 6c 65 20 70 61 72 73  ccurs while pars
38a0: 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  ing or evaluatin
38b0: 67 20 61 6e 79 20 6f 66 20 74 68 65 20 53 51 4c  g any of the SQL
38c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61  .**          sta
38d0: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 53  tements in the S
38e0: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
38f0: 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c  qlite3_exec(D,S,
3900: 43 2c 41 2c 45 29 5d 20 61 6e 64 20 69 66 0a 2a  C,A,E)] and if.*
3910: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 45  *          the E
3920: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
3930: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 73 71  t NULL, then [sq
3940: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68  lite3_exec()] sh
3950: 61 6c 6c 20 73 74 6f 72 65 0a 2a 2a 20 20 20 20  all store.**    
3960: 20 20 20 20 20 20 69 6e 20 2a 45 20 61 6e 20 61        in *E an a
3970: 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
3980: 20 6d 65 73 73 61 67 65 20 77 72 69 74 74 65 6e   message written
3990: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
39a0: 61 69 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  ained.**        
39b0: 20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f    from [sqlite3_
39c0: 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a  malloc()]..**.**
39d0: 20 7b 48 31 32 31 33 34 7d 20 54 68 65 20 5b 73   {H12134} The [s
39e0: 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c  qlite3_exec(D,S,
39f0: 43 2c 41 2c 45 29 5d 20 72 6f 75 74 69 6e 65 20  C,A,E)] routine 
3a00: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 76 61  shall set the va
3a10: 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  lue of.**       
3a20: 20 20 20 2a 45 20 74 6f 20 4e 55 4c 4c 20 69 66     *E to NULL if
3a30: 20 45 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61   E is not NULL a
3a40: 6e 64 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  nd there are no 
3a50: 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  errors..**.** {H
3a60: 31 32 31 33 37 7d 20 54 68 65 20 5b 73 71 6c 69  12137} The [sqli
3a70: 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41  te3_exec(D,S,C,A
3a80: 2c 45 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68  ,E)] function sh
3a90: 61 6c 6c 20 73 65 74 20 74 68 65 20 5b 65 72 72  all set the [err
3aa0: 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 20 20 20 20  or code].**     
3ab0: 20 20 20 20 20 61 6e 64 20 6d 65 73 73 61 67 65       and message
3ac0: 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20   accessible via 
3ad0: 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
3ae0: 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
3af0: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
3b00: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
3b10: 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a  3_errmsg16()]..*
3b20: 2a 0a 2a 2a 20 7b 48 31 32 31 33 38 7d 20 49 66  *.** {H12138} If
3b30: 20 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72   the S parameter
3b40: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
3b50: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73  c(D,S,C,A,E)] is
3b60: 20 4e 55 4c 4c 20 6f 72 20 61 6e 0a 2a 2a 20 20   NULL or an.**  
3b70: 20 20 20 20 20 20 20 20 65 6d 70 74 79 20 73 74          empty st
3b80: 72 69 6e 67 20 6f 72 20 63 6f 6e 74 61 69 6e 73  ring or contains
3b90: 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74   nothing other t
3ba0: 68 61 6e 20 77 68 69 74 65 73 70 61 63 65 2c 20  han whitespace, 
3bb0: 63 6f 6d 6d 65 6e 74 73 2c 0a 2a 2a 20 20 20 20  comments,.**    
3bc0: 20 20 20 20 20 20 61 6e 64 2f 6f 72 20 73 65 6d        and/or sem
3bd0: 69 63 6f 6c 6f 6e 73 2c 20 74 68 65 6e 20 72 65  icolons, then re
3be0: 73 75 6c 74 73 20 6f 66 20 5b 73 71 6c 69 74 65  sults of [sqlite
3bf0: 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a  3_errcode()],.**
3c00: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
3c10: 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e  e3_errmsg()], an
3c20: 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d [sqlite3_errms
3c30: 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  g16()].**       
3c40: 20 20 20 73 68 61 6c 6c 20 72 65 73 65 74 20 74     shall reset t
3c50: 6f 20 69 6e 64 69 63 61 74 65 20 6e 6f 20 65 72  o indicate no er
3c60: 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55  rors..**.** ASSU
3c70: 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  MPTIONS:.**.** {
3c80: 41 31 32 31 34 31 7d 20 54 68 65 20 66 69 72 73  A12141} The firs
3c90: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
3ca0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3cb0: 6d 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64  must be an valid
3cc0: 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20 20 20   and open.**    
3cd0: 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
3ce0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  connection]..**.
3cf0: 2a 2a 20 7b 41 31 32 31 34 32 7d 20 54 68 65 20  ** {A12142} The 
3d00: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3d10: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  ion must not be 
3d20: 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20  closed while.** 
3d30: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
3d40: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e  3_exec()] is run
3d50: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  ning..**.** {A12
3d60: 31 34 33 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67  143} The calling
3d70: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
3d80: 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 72   use [sqlite3_fr
3d90: 65 65 28 29 5d 20 74 6f 20 66 72 65 65 0a 2a 2a  ee()] to free.**
3da0: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6d 65            the me
3db0: 6d 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73  mory that *errms
3dc0: 67 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  g is left pointi
3dd0: 6e 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65  ng at once the e
3de0: 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rror.**         
3df0: 20 6d 65 73 73 61 67 65 20 69 73 20 6e 6f 20 6c   message is no l
3e00: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
3e10: 0a 2a 2a 20 7b 41 31 32 31 34 35 7d 20 54 68 65  .** {A12145} The
3e20: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
3e30: 65 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70  ext in the 2nd p
3e40: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
3e50: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20  ite3_exec()].** 
3e60: 20 20 20 20 20 20 20 20 20 6d 75 73 74 20 72 65           must re
3e70: 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 77  main unchanged w
3e80: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 78  hile [sqlite3_ex
3e90: 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  ec()] is running
3ea0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
3eb0: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
3ec0: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
3ed0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ee0: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
3ef0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
3f00: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
3f10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3f20: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
3f30: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
3f40: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
3f50: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3f60: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
3f70: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
3f80: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
3f90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fa0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fb0: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
3fc0: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
3fd0: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
3fe0: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
3ff0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4000: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
4010: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
4020: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4030: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48   Result Codes {H
4040: 31 30 32 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a  10210} <S10700>.
4050: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
4060: 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f  ITE_OK {error co
4070: 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73  de} {error codes
4080: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
4090: 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65  result code} {re
40a0: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a  sult codes}.**.*
40b0: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75  * Many SQLite fu
40c0: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61  nctions return a
40d0: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74  n integer result
40e0: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73   code from the s
40f0: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65  et shown.** here
4100: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64   in order to ind
4110: 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f  icates success o
4120: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
4130: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
4140: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
4150: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
4160: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
4170: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c  * See also: [SQL
4180: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
4190: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
41a0: 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69   codes].*/.#defi
41b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20  ne SQLITE_OK    
41c0: 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75         0   /* Su
41d0: 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20  ccessful result 
41e0: 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d  */./* beginning-
41f0: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4200: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4210: 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20  _ERROR        1 
4220: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f    /* SQL error o
4230: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61  r missing databa
4240: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
4250: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20  LITE_INTERNAL   
4260: 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61    2   /* Interna
4270: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  l logic error in
4280: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69   SQLite */.#defi
4290: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20  ne SQLITE_PERM  
42a0: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63         3   /* Ac
42b0: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20  cess permission 
42c0: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
42d0: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20  e SQLITE_ABORT  
42e0: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c        4   /* Cal
42f0: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
4300: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74  quested an abort
4310: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4320: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20  TE_BUSY         
4330: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  5   /* The datab
4340: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b  ase file is lock
4350: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4360: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20  LITE_LOCKED     
4370: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65    6   /* A table
4380: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
4390: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
43a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d  efine SQLITE_NOM
43b0: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  EM        7   /*
43c0: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c   A malloc() fail
43d0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
43e0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20  LITE_READONLY   
43f0: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74    8   /* Attempt
4400: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64   to write a read
4410: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f  only database */
4420: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4430: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20  INTERRUPT    9  
4440: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65   /* Operation te
4450: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69  rminated by sqli
4460: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a  te3_interrupt()*
4470: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4480: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20  _IOERR       10 
4490: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f    /* Some kind o
44a0: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72  f disk I/O error
44b0: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65   occurred */.#de
44c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
44d0: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20  UPT     11   /* 
44e0: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73  The database dis
44f0: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f  k image is malfo
4500: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rmed */.#define 
4510: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
4520: 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55     12   /* NOT U
4530: 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65  SED. Table or re
4540: 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a  cord not found *
4550: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4560: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
4570: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
4580: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
4590: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
45a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45b0: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
45c0: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
45d0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
45e0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
45f0: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
4600: 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20      15   /* NOT 
4610: 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c  USED. Database l
4620: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72  ock protocol err
4630: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4640: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20  LITE_EMPTY      
4650: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   16   /* Databas
4660: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64  e is empty */.#d
4670: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
4680: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
4690: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
46a0: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
46b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
46c0: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
46d0: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
46e0: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
46f0: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
4700: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
4710: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
4720: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
4730: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
4740: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4750: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
4760: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
4770: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
4780: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4790: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
47a0: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
47b0: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
47c0: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
47d0: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
47e0: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
47f0: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4800: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4810: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4820: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
4830: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
4840: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4850: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
4860: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74  /* Auxiliary dat
4870: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72  abase format err
4880: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4890: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20  LITE_RANGE      
48a0: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72   25   /* 2nd par
48b0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
48c0: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61  3_bind out of ra
48d0: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge */.#define S
48e0: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20  QLITE_NOTADB    
48f0: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f    26   /* File o
4900: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f  pened that is no
4910: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
4920: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4930: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20  ITE_ROW         
4940: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  100  /* sqlite3_
4950: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68  step() has anoth
4960: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a  er row ready */.
4970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
4980: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20  ONE        101  
4990: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
49a0: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  ) has finished e
49b0: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65  xecuting */./* e
49c0: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  nd-of-error-code
49d0: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s */../*.** CAPI
49e0: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52  3REF: Extended R
49f0: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 30  esult Codes {H10
4a00: 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  220} <S10700>.**
4a10: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4a20: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d  nded error code}
4a30: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
4a40: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f   codes}.** KEYWO
4a50: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4a60: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74  esult code} {ext
4a70: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4a80: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
4a90: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4aa0: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4ab0: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4ac0: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4ad0: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
4ae0: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
4af0: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
4b00: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
4b10: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
4b20: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
4b30: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
4b40: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
4b50: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
4b60: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
4b70: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
4b80: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
4b90: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
4ba0: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4bb0: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4bc0: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4bd0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
4be0: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
4bf0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4c00: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4c10: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
4c20: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
4c30: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4c40: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4c50: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4c60: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
4c70: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
4c80: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4c90: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4ca0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4cb0: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4cc0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4cd0: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
4ce0: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a  des()] API..**.*
4cf0: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
4d00: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
4d10: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4d20: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a  e listed here..*
4d30: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74  * One may expect
4d40: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
4d50: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4d60: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70  odes will be exp
4d70: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65  and.** over time
4d80: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
4d90: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72   uses extended r
4da0: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75  esult codes shou
4db0: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20  ld expect.** to 
4dc0: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63  see new result c
4dd0: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  odes in future r
4de0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
4df0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  e..**.** The SQL
4e00: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f  ITE_OK result co
4e10: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65  de will never be
4e20: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77   extended.  It w
4e30: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  ill always.** be
4e40: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a   exactly zero..*
4e50: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
4e60: 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 33 7d 20  .**.** {H10223} 
4e70: 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d  The symbolic nam
4e80: 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65  e for an extende
4e90: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 73 68  d result code sh
4ea0: 61 6c 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  all contains.** 
4eb0: 20 20 20 20 20 20 20 20 20 61 20 72 65 6c 61 74           a relat
4ec0: 65 64 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c  ed primary resul
4ed0: 74 20 63 6f 64 65 20 61 73 20 61 20 70 72 65 66  t code as a pref
4ee0: 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32  ix..**.** {H1022
4ef0: 34 7d 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c  4} Primary resul
4f00: 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61  t code names sha
4f10: 6c 6c 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e  ll contain a sin
4f20: 67 6c 65 20 22 5f 22 20 63 68 61 72 61 63 74 65  gle "_" characte
4f30: 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 35  r..**.** {H10225
4f40: 7d 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c  } Extended resul
4f50: 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61  t code names sha
4f60: 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f  ll contain two o
4f70: 72 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61  r more "_" chara
4f80: 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  cters..**.** {H1
4f90: 30 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 69  0226} The numeri
4fa0: 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78  c value of an ex
4fb0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4fc0: 64 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e  de shall contain
4fd0: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
4fe0: 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f   numeric value o
4ff0: 66 20 69 74 73 20 63 6f 72 72 65 73 70 6f 6e 64  f its correspond
5000: 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65 73 75  ing primary resu
5010: 6c 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20 20 20  lt code in.**   
5020: 20 20 20 20 20 20 20 69 74 73 20 6c 65 61 73 74         its least
5030: 20 73 69 67 6e 69 66 69 63 61 6e 74 20 38 20 62   significant 8 b
5040: 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  its..*/.#define 
5050: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
5060: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  D              (
5070: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5080: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5090: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
50a0: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53  T_READ        (S
50b0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
50c0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
50d0: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45  LITE_IOERR_WRITE
50e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
50f0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
5100: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5110: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
5120: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5130: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c  ITE_IOERR | (4<<
5140: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5150: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59  TE_IOERR_DIR_FSY
5160: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
5170: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
5180: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5190: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
51a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51b0: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29  E_IOERR | (6<<8)
51c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51d0: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20  _IOERR_FSTAT    
51e0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
51f0: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
5200: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5210: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
5220: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5230: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a  IOERR | (8<<8)).
5240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5250: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20  OERR_RDLOCK     
5260: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5270: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
5280: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5290: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
52a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
52b0: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23  ERR | (10<<8)).#
52c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52d0: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20  ERR_BLOCKED     
52e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
52f0: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23  ERR | (11<<8)).#
5300: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5310: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ERR_NOMEM       
5320: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5330: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23  ERR | (12<<8)).#
5340: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5350: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20  ERR_ACCESS      
5360: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5370: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23  ERR | (13<<8)).#
5380: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5390: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45  ERR_CHECKRESERVE
53a0: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f  DLOCK (SQLITE_IO
53b0: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 0a  ERR | (14<<8))..
53c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
53d0: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
53e0: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b  pen Operations {
53f0: 48 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e  H10230} <H11120>
5400: 20 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H12700>.**.** 
5410: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
5420: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
5430: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20  r use in the.** 
5440: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
5450: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
5460: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
5470: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65  ce and.** in the
5480: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
5490: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
54a0: 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  od of the.** [sq
54b0: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
54c0: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
54d0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
54e0: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
54f0: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
5500: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
5510: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
5520: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
5530: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
5540: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5550: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
5560: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
5570: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
5580: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
5590: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
55a0: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
55b0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
55c0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
55d0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
55e0: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
55f0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
5600: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
5610: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
5620: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
5630: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
5640: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
5650: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
5660: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
5670: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
5680: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
5690: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
56a0: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
56b0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
56c0: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
56d0: 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  02000.#define SQ
56e0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
56f0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
5700: 30 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  04000.#define SQ
5710: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
5720: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
5730: 30 38 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  08000../*.** CAP
5740: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
5750: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48  aracteristics {H
5760: 31 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a  10240} <H11120>.
5770: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
5780: 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65  eCapabilities me
5790: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
57a0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
57b0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
57c0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
57d0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
57e0: 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20  of the these.** 
57f0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
5800: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
5810: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
5820: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
5830: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
5840: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
5850: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
5860: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
5870: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
5880: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5890: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
58a0: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
58b0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
58c0: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
58d0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
58e0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
58f0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
5900: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
5910: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
5920: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
5930: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
5940: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
5950: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
5960: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
5970: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
5980: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5990: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
59a0: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
59b0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
59c0: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
59d0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
59e0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
59f0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
5a00: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
5a10: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
5a20: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
5a30: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
5a40: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
5a50: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
5a60: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
5a70: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
5a80: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
5a90: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
5aa0: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
5ab0: 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  e()..*/.#define 
5ac0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5ad0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30  MIC          0x0
5ae0: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20  0000001.#define 
5af0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b00: 4d 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30  MIC512       0x0
5b10: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
5b20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b30: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30  MIC1K        0x0
5b40: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
5b50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b60: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30  MIC2K        0x0
5b70: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
5b80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b90: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30  MIC4K        0x0
5ba0: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
5bb0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5bc0: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30  MIC8K        0x0
5bd0: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
5be0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5bf0: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30  MIC16K       0x0
5c00: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
5c10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5c20: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30  MIC32K       0x0
5c30: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
5c40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5c50: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30  MIC64K       0x0
5c60: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
5c70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
5c80: 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30  E_APPEND     0x0
5c90: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
5ca0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
5cb0: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30  UENTIAL      0x0
5cc0: 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0000400../*.** C
5cd0: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
5ce0: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31  cking Levels {H1
5cf0: 30 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c  0250} <H11120> <
5d00: 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51  H11310>.**.** SQ
5d10: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66  Lite uses one of
5d20: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
5d30: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
5d40: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ond.** argument 
5d50: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65  to calls it make
5d60: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29  s to the xLock()
5d70: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d   and xUnlock() m
5d80: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20  ethods.** of an 
5d90: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
5da0: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ods] object..*/.
5db0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5dc0: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20  OCK_NONE        
5dd0: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
5de0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20  TE_LOCK_SHARED  
5df0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
5e00: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
5e10: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66  RVED      2.#def
5e20: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5e30: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a  PENDING       3.
5e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5e50: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20  OCK_EXCLUSIVE   
5e60: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    4../*.** CAPI3
5e70: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61  REF: Synchroniza
5e80: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20  tion Type Flags 
5e90: 7b 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30  {H10260} <H11120
5ea0: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  >.**.** When SQL
5eb0: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
5ec0: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
5ed0: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
5ee0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5ef0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
5f00: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
5f10: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
5f20: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
5f30: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
5f40: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
5f50: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
5f60: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
5f70: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
5f80: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
5f90: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
5fa0: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
5fb0: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
5fc0: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
5fd0: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
5fe0: 6c 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c 49  lushed. The SQLI
5ff0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66  TE_SYNC_NORMAL f
6000: 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  lag means.** to 
6010: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  use normal fsync
6020: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68  () semantics. Th
6030: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
6040: 4c 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a  LL flag means.**
6050: 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 2d 58   to use Mac OS-X
6060: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20   style fullsync 
6070: 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63  instead of fsync
6080: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
6090: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
60a0: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32  L        0x00002
60b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
60c0: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20  SYNC_FULL       
60d0: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69     0x00003.#defi
60e0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  ne SQLITE_SYNC_D
60f0: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30  ATAONLY      0x0
6100: 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0010../*.** CAPI
6110: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
6120: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
6130: 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 32  dle {H11110} <S2
6140: 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  0110>.**.** An [
6150: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
6160: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
6170: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
6180: 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66  the OS.** interf
6190: 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69  ace layer.  Indi
61a0: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
61b0: 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ace implementati
61c0: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
61d0: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
61e0: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
61f0: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
6200: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
6210: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
6220: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
6230: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
6240: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
6250: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6260: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
6270: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
6280: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
6290: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
62a0: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
62b0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
62c0: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
62d0: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
62e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
62f0: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
6300: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6310: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
6320: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
6330: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
6340: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6350: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
6360: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
6370: 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 32 30  s Object {H11120
6380: 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a  } <S20110>.**.**
6390: 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e   Every file open
63a0: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
63b0: 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65  e3_vfs] xOpen me
63c0: 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61  thod populates a
63d0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  n.** [sqlite3_fi
63e0: 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20  le] object (or, 
63f0: 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61  more commonly, a
6400: 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
6410: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
6420: 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20  e] object) with 
6430: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
6440: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
6450: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73   object..** This
6460: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
6470: 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64  the methods used
6480: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
6490: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ous operations.*
64a0: 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70  * against the op
64b0: 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e  en file represen
64c0: 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ted by the [sqli
64d0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
64e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
64f0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
6500: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
6510: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
6520: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
6530: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
6540: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
6550: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
6560: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
6570: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
6580: 73 20 61 20 4d 61 63 20 4f 53 2d 58 20 73 74 79  s a Mac OS-X sty
6590: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
65a0: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
65b0: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
65c0: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
65d0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
65e0: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
65f0: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
6600: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
6610: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
6620: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
6630: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
6640: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
6650: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
6660: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
6670: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
6680: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
6690: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
66a0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
66b0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
66c0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
66d0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
66e0: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
66f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
6700: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
6710: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
6720: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
6730: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
6740: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
6750: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
6760: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
6770: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
6780: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
6790: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
67a0: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
67b0: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
67c0: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
67d0: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
67e0: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
67f0: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
6800: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
6810: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
6820: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
6830: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
6840: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
6850: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
6860: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
6870: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
6880: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
6890: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
68a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
68b0: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
68c0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
68d0: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
68e0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
68f0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
6900: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
6910: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
6920: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
6930: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
6940: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
6950: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
6960: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
6970: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
6980: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
6990: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
69a0: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
69b0: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
69c0: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
69d0: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
69e0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
69f0: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
6a00: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
6a10: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
6a20: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
6a30: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
6a40: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
6a50: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
6a60: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
6a70: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
6a80: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
6a90: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
6aa0: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
6ab0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
6ac0: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
6ad0: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
6ae0: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
6af0: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
6b00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
6b10: 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66  KSTATE | list of
6b20: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
6b30: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
6b40: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
6b50: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
6b60: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
6b70: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
6b80: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
6b90: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
6ba0: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
6bb0: 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20  onflicts..**.** 
6bc0: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
6bd0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
6be0: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
6bf0: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
6c00: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
6c10: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
6c20: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
6c30: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
6c40: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
6c50: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
6c60: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
6c70: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
6c80: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
6c90: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
6ca0: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
6cb0: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
6cc0: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
6cd0: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
6ce0: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
6cf0: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
6d00: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
6d10: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
6d20: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6d30: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
6d40: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6d50: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
6d60: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6d70: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
6d80: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6d90: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
6da0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6db0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
6dc0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6dd0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
6de0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6df0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
6e00: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
6e10: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6e20: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
6e30: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
6e40: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
6e50: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
6e60: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75  QUENTIAL].** </u
6e70: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
6e80: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6e90: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6ea0: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
6eb0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
6ec0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6ed0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6ee0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
6ef0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
6f00: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
6f10: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
6f20: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
6f30: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
6f40: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
6f50: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
6f60: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
6f70: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6f80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6f90: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
6fa0: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
6fb0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
6fc0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
6fd0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
6fe0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
6ff0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
7000: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
7010: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
7020: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
7030: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
7040: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
7050: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
7060: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
7070: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
7080: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
7090: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
70a0: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
70b0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
70c0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
70d0: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f  hods sqlite3_io_
70e0: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
70f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7100: 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  ds {.  int iVers
7110: 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c  ion;.  int (*xCl
7120: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ose)(sqlite3_fil
7130: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65  e*);.  int (*xRe
7140: 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ad)(sqlite3_file
7150: 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  *, void*, int iA
7160: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
7170: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
7180: 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65  (*xWrite)(sqlite
7190: 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76  3_file*, const v
71a0: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
71b0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
71c0: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54  fst);.  int (*xT
71d0: 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33  runcate)(sqlite3
71e0: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
71f0: 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69  int64 size);.  i
7200: 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
7210: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66  te3_file*, int f
7220: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
7230: 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65  FileSize)(sqlite
7240: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
7250: 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a  _int64 *pSize);.
7260: 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73    int (*xLock)(s
7270: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7280: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c  t);.  int (*xUnl
7290: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
72a0: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
72b0: 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  (*xCheckReserved
72c0: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
72d0: 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  le*, int *pResOu
72e0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  t);.  int (*xFil
72f0: 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65  eControl)(sqlite
7300: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c  3_file*, int op,
7310: 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20   void *pArg);.  
7320: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a  int (*xSectorSiz
7330: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7340: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69  );.  int (*xDevi
7350: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
7360: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  s)(sqlite3_file*
7370: 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  );.  /* Addition
7380: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
7390: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
73a0: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
73b0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
73c0: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20  : Standard File 
73d0: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20  Control Opcodes 
73e0: 7b 48 31 31 33 31 30 7d 20 3c 53 33 30 38 30 30  {H11310} <S30800
73f0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  >.**.** These in
7400: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
7410: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
7420: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
7430: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
7440: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
7450: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
7460: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
7470: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7480: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
7490: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
74a0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
74b0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
74c0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
74d0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
74e0: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
74f0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7500: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
7510: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
7520: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
7530: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
7540: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
7550: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
7560: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
7570: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
7580: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
7590: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
75a0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
75b0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
75c0: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
75d0: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
75e0: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
75f0: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
7600: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e  g testing and on
7610: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  ly needs to be s
7620: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51  upported when SQ
7630: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20  LITE_TEST.** is 
7640: 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66  defined..*/.#def
7650: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
7660: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
7670: 20 20 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    1../*.** CAPI3
7680: 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c  REF: Mutex Handl
7690: 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 32 30 31  e {H17110} <S201
76a0: 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75  30>.**.** The mu
76b0: 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69  tex module withi
76c0: 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73  n SQLite defines
76d0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
76e0: 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73   to be an.** abs
76f0: 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61  tract type for a
7700: 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20   mutex object.  
7710: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
7720: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61  never looks.** a
7730: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  t the internal r
7740: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66  epresentation of
7750: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74   an [sqlite3_mut
7760: 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a  ex].  It only.**
7770: 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e   deals with poin
7780: 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  ters to the [sql
7790: 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65  ite3_mutex] obje
77a0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65  ct..**.** Mutexe
77b0: 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73  s are created us
77c0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
77d0: 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  ex_alloc()]..*/.
77e0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
77f0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c  qlite3_mutex sql
7800: 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a  ite3_mutex;../*.
7810: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7820: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74  Interface Object
7830: 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 30 31 30   {H11140} <S2010
7840: 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  0>.**.** An inst
7850: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
7860: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64  te3_vfs object d
7870: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
7880: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20  face between.** 
7890: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
78a0: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
78b0: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
78c0: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
78d0: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
78e0: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
78f0: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
7900: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a   file system"..*
7910: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
7920: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
7930: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
7940: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
7950: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
7960: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
7970: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
7980: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
7990: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
79a0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
79b0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
79c0: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
79d0: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
79e0: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
79f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
7a00: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
7a10: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
7a20: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
7a30: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
7a40: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
7a50: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
7a60: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
7a70: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
7a80: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
7a90: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
7aa0: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
7ab0: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
7ac0: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
7ad0: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
7ae0: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
7af0: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
7b00: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
7b10: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
7b20: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
7b30: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
7b40: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
7b50: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
7b60: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
7b70: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
7b80: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
7b90: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
7ba0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
7bb0: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
7bc0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
7bd0: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
7be0: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
7bf0: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
7c00: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
7c10: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
7c20: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
7c30: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
7c40: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
7c50: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
7c60: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
7c70: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
7c80: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
7c90: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
7ca0: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
7cb0: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
7cc0: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
7cd0: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
7ce0: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
7cf0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
7d00: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
7d10: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
7d20: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
7d30: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
7d40: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
7d50: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
7d60: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
7d70: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
7d80: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
7d90: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
7da0: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
7db0: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
7dc0: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
7dd0: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
7de0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
7df0: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
7e00: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
7e10: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
7e20: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
7e30: 2a 20 7b 48 31 31 31 34 31 7d 20 53 51 4c 69 74  * {H11141} SQLit
7e40: 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65  e will guarantee
7e50: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
7e60: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
7e70: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
7e80: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
7e90: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
7ea0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
7eb0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 20  ullPathname().  
7ec0: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67  SQLite further g
7ed0: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a  uarantees that.*
7ee0: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  * the string wil
7ef0: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
7f00: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
7f10: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
7f20: 6c 6c 65 64 2e 20 7b 45 4e 44 7d 20 20 42 65 63  lled. {END}  Bec
7f30: 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76  ause of the prev
7f40: 69 6f 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a 2a  ious sentense,.*
7f50: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  * the [sqlite3_f
7f60: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20  ile] can safely 
7f70: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20  store a pointer 
7f80: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  to the.** filena
7f90: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74  me if it needs t
7fa0: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66  o remember the f
7fb0: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65  ilename for some
7fc0: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74   reason..** If t
7fd0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
7fe0: 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20  ameter is xOpen 
7ff0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
8000: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20  r then xOpen.** 
8010: 6d 75 73 74 20 69 6e 76 69 74 65 20 69 74 73 20  must invite its 
8020: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61  own temporary na
8030: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e  me for the file.
8040: 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a    Whenever the .
8050: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
8060: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
8070: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
8080: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
8090: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
80a0: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
80b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
80c0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
80d0: 0a 2a 2a 20 7b 48 31 31 31 34 32 7d 20 54 68 65  .** {H11142} The
80e0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
80f0: 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75  to xOpen() inclu
8100: 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74  des all bits set
8110: 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73   in.** the flags
8120: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
8130: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
8140: 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65  .  Or if [sqlite
8150: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20  3_open()].** or 
8160: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
8170: 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  )] is used, then
8180: 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20   flags includes 
8190: 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c  at least.** [SQL
81a0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
81b0: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
81c0: 45 4e 5f 43 52 45 41 54 45 5d 2e 20 7b 45 4e 44  EN_CREATE]. {END
81d0: 7d 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20  }.** If xOpen() 
81e0: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
81f0: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
8200: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
8210: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
8220: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
8230: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
8240: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
8250: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
8260: 20 7b 48 31 31 31 34 33 7d 20 53 51 4c 69 74 65   {H11143} SQLite
8270: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
8280: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
8290: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
82a0: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
82b0: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
82c0: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
82d0: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
82e0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
82f0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
8300: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
8310: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
8320: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
8330: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
8340: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
8350: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
8360: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
8370: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
8380: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
8390: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
83a0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
83b0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
83c0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
83d0: 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45  NAL].** </ul> {E
83e0: 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ND}.**.** The fi
83f0: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
8400: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
8410: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
8420: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
8430: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
8440: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
8450: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
8460: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
8470: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
8480: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
8490: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
84a0: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
84b0: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
84c0: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
84d0: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
84e0: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
84f0: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
8500: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
8510: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
8520: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
8530: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
8540: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
8550: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
8560: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
8570: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
8580: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
8590: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
85a0: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
85b0: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
85c0: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
85d0: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
85e0: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
85f0: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
8600: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
8610: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
8620: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
8630: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
8640: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
8650: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
8660: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8670: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
8680: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
8690: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
86a0: 2a 20 7b 48 31 31 31 34 35 7d 20 54 68 65 20 5b  * {H11145} The [
86b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
86c0: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20  TEONCLOSE] flag 
86d0: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
86e0: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65  hould be.** dele
86f0: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  ted when it is c
8700: 6c 6f 73 65 64 2e 20 20 7b 48 31 31 31 34 36 7d  losed.  {H11146}
8710: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
8720: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
8730: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
8740: 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 61  for TEMP  databa
8750: 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e  ses, journals an
8760: 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c  d for subjournal
8770: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 37  s..**.** {H11147
8780: 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  } The [SQLITE_OP
8790: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c  EN_EXCLUSIVE] fl
87a0: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
87b0: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e  e should be open
87c0: 65 64 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  ed.** for exclus
87d0: 69 76 65 20 61 63 63 65 73 73 2e 20 20 54 68 69  ive access.  Thi
87e0: 73 20 66 6c 61 67 20 69 73 20 73 65 74 20 66 6f  s flag is set fo
87f0: 72 20 61 6c 6c 20 66 69 6c 65 73 20 65 78 63 65  r all files exce
8800: 70 74 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 61  pt.** for the ma
8810: 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
8820: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 38 7d  ..**.** {H11148}
8830: 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69   At least szOsFi
8840: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
8850: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
8860: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
8870: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
8880: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
8890: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
88a0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
88b0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 7b 45  ent to xOpen. {E
88c0: 4e 44 7d 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  ND}  The xOpen m
88d0: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68  ethod does not h
88e0: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61  ave to.** alloca
88f0: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65  te the structure
8900: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74  ; it should just
8910: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 0a   fill it in..**.
8920: 2a 2a 20 7b 48 31 31 31 34 39 7d 20 54 68 65 20  ** {H11149} The 
8930: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
8940: 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20  o xAccess() may 
8950: 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  be [SQLITE_ACCES
8960: 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20  S_EXISTS].** to 
8970: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
8980: 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stence of a file
8990: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
89a0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74  ESS_READWRITE] t
89b0: 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65  o.** test whethe
89c0: 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64  r a file is read
89d0: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
89e0: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
89f0: 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f  CESS_READ].** to
8a00: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
8a10: 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74  file is at least
8a20: 20 72 65 61 64 61 62 6c 65 2e 20 7b 45 4e 44 7d   readable. {END}
8a30: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
8a40: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
8a50: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 35 30 7d  ..**.** {H11150}
8a60: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77   SQLite will alw
8a70: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
8a80: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
8a90: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
8aa0: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
8ab0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
8ac0: 20 7b 48 31 31 31 35 31 7d 20 54 68 65 20 65 78   {H11151} The ex
8ad0: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
8ae0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
8af0: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
8b00: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
8b10: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
8b20: 20 7b 45 4e 44 7d 20 20 49 66 20 74 68 65 20 6f   {END}  If the o
8b30: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
8b40: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
8b50: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
8b60: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
8b70: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
8b80: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
8b90: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
8ba0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
8bb0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
8bc0: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
8bd0: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
8be0: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
8bf0: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
8c00: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
8c10: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
8c20: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
8c30: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61  s(), xSleep(), a
8c40: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  nd xCurrentTime(
8c50: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
8c60: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
8c70: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
8c80: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
8c90: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
8ca0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
8cb0: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
8cc0: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
8cd0: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
8ce0: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
8cf0: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
8d00: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
8d10: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
8d20: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
8d30: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
8d40: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
8d50: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
8d60: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
8d70: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
8d80: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
8d90: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
8da0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
8db0: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
8dc0: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
8dd0: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
8de0: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43  s given.  The xC
8df0: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
8e00: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
8e10: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
8e20: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
8e30: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
8e40: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
8e50: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
8e60: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72  sqlite3_vfs;.str
8e70: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
8e80: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
8e90: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
8ea0: 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f  Structure versio
8eb0: 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e  n number */.  in
8ec0: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
8ed0: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
8ee0: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
8ef0: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
8f00: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
8f10: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
8f20: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
8f30: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
8f40: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
8f50: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
8f60: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
8f70: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
8f80: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
8f90: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
8fa0: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
8fb0: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
8fc0: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
8fd0: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
8fe0: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
8ff0: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
9000: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
9010: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
9020: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
9030: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
9040: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
9050: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
9060: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
9070: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
9080: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
9090: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
90a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
90b0: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
90c0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
90d0: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
90e0: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
90f0: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
9100: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
9110: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
9120: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
9130: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
9140: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
9150: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
9160: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
9170: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
9180: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
9190: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
91a0: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
91b0: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53  ;.  void *(*xDlS
91c0: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
91d0: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
91e0: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20  ar *zSymbol);.  
91f0: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
9200: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
9210: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
9220: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
9230: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
9240: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
9250: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
9260: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9270: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
9280: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
9290: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
92a0: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
92b0: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
92c0: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
92d0: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
92e0: 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65  *);.  /* New fie
92f0: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
9300: 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65  ded in figure ve
9310: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
9320: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
9330: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
9340: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
9350: 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ppens. */.};../*
9360: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
9370: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
9380: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 20 7b  ess VFS method {
9390: 48 31 31 31 39 30 7d 20 3c 48 31 31 31 34 30 3e  H11190} <H11140>
93a0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 39 31 7d 20  .**.** {H11191} 
93b0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
93c0: 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75  nstants can be u
93d0: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
93e0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
93f0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
9400: 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  hod of an [sqlit
9410: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
9420: 7b 45 4e 44 7d 20 20 54 68 65 79 20 64 65 74 65  {END}  They dete
9430: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
9440: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
9450: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
9460: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
9470: 66 6f 72 2e 0a 2a 2a 20 7b 48 31 31 31 39 32 7d  for..** {H11192}
9480: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
9490: 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20  ESS_EXISTS, the 
94a0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
94b0: 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20  * simply checks 
94c0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
94d0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 7b 48 31 31   exists..** {H11
94e0: 31 39 33 7d 20 57 69 74 68 20 53 51 4c 49 54 45  193} With SQLITE
94f0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
9500: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
9510: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
9520: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
9530: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
9540: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a  e and writable..
9550: 2a 2a 20 7b 48 31 31 31 39 34 7d 20 57 69 74 68  ** {H11194} With
9560: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
9570: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
9580: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
9590: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
95a0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a  le is readable..
95b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
95c0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
95d0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
95e0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
95f0: 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53  RITE 1.#define S
9600: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
9610: 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20  D      2../*.** 
9620: 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61  CAPI3REF: Initia
9630: 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20  lize The SQLite 
9640: 4c 69 62 72 61 72 79 20 7b 48 31 30 31 33 30 7d  Library {H10130}
9650: 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 31 30 30   <S20000><S30100
9660: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
9670: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9680: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
9690: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
96a0: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
96b0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
96c0: 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64  n() routine.** d
96d0: 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72  eallocates any r
96e0: 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65  esources that we
96f0: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
9700: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9710: 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ze()..**.** A ca
9720: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
9730: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e  itialize() is an
9740: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
9750: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68  l if it is.** th
9760: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
9770: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9780: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72  ) is invoked dur
9790: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
97a0: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65   of.** the proce
97b0: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20  ss, or if it is 
97c0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
97d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
97e0: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
97f0: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  * following a ca
9800: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
9810: 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 20  utdown().  Only 
9820: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
9830: 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  l.** of sqlite3_
9840: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65  initialize() doe
9850: 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61  s any initializa
9860: 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72  tion.  All other
9870: 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61   calls.** are ha
9880: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a  rmless no-ops..*
9890: 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72  *.** Among other
98a0: 20 74 68 69 6e 67 73 2c 20 73 71 6c 69 74 65 33   things, sqlite3
98b0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 68  _initialize() sh
98c0: 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  all invoke.** sq
98d0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
98e0: 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 73 71 6c    Similarly, sql
98f0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
9900: 2a 2a 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 20  ** shall invoke 
9910: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
9920: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
9930: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9940: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
9950: 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75   SQLITE_OK on su
9960: 63 63 65 73 73 2e 0a 2a 2a 20 49 66 20 66 6f 72  ccess..** If for
9970: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
9980: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9990: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
99a0: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
99b0: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
99c0: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
99d0: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
99e0: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
99f0: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
9a00: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
9a10: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
9a20: 65 72 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4f  er than SQLITE_O
9a30: 4b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  K..**.** The sql
9a40: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9a50: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
9a60: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
9a70: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
9a80: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
9a90: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
9aa0: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
9ab0: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
9ac0: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
9ad0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9ae0: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
9af0: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
9b00: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
9b10: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
9b20: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
9b30: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
9b40: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
9b50: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
9b60: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
9b70: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
9b80: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
9b90: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
9ba0: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 48 6f 77  ** already.  How
9bb0: 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20  ever, if SQLite 
9bc0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
9bd0: 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
9be0: 5f 41 55 54 4f 49 4e 49 54 0a 2a 2a 20 63 6f 6d  _AUTOINIT.** com
9bf0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
9c00: 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d  , then the autom
9c10: 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71  atic calls to sq
9c20: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9c30: 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65  ().** are omitte
9c40: 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  d and the applic
9c50: 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20  ation must call 
9c60: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9c70: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a  ze() directly.**
9c80: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
9c90: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
9ca0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72   interface.  For
9cb0: 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69   maximum portabi
9cc0: 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72  lity,.** it is r
9cd0: 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
9ce0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77  applications alw
9cf0: 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ays invoke sqlit
9d00: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
9d10: 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f  ** directly prio
9d20: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
9d30: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
9d40: 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72  rface.  Future r
9d50: 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51  eleases.** of SQ
9d60: 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65  Lite may require
9d70: 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72   this.  In other
9d80: 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61   words, the beha
9d90: 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a  vior exhibited.*
9da0: 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
9db0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 53   compiled with S
9dc0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
9dd0: 4e 49 54 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  NIT might become
9de0: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
9df0: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
9e00: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
9e10: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
9e20: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
9e30: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
9e40: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
9e50: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
9e60: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
9e70: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
9e80: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
9e90: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
9ea0: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
9eb0: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
9ec0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
9ed0: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
9ee0: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
9ef0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
9f00: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
9f10: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
9f20: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
9f30: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
9f40: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
9f50: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
9f60: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
9f70: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
9f80: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
9f90: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
9fa0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
9fb0: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
9fc0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
9fd0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
9fe0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
9ff0: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
a000: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a010: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
a020: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
a030: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
a040: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
a050: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
a060: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
a070: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
a080: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
a090: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
a0a0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
a0b0: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
a0c0: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
a0d0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
a0e0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a0f0: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
a100: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a110: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
a120: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
a130: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
a140: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
a150: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
a160: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
a170: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
a180: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 75  s compiled for u
a190: 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c 20 6f 72  nix, windows, or
a1a0: 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 62   os/2..** When b
a1b0: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
a1c0: 6c 61 74 66 6f 72 6d 73 20 28 75 73 69 6e 67 20  latforms (using 
a1d0: 74 68 65 20 53 51 4c 49 54 45 5f 4f 53 5f 4f 54  the SQLITE_OS_OT
a1e0: 48 45 52 3d 31 20 63 6f 6d 70 69 6c 65 2d 74 69  HER=1 compile-ti
a1f0: 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
a200: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
a210: 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
a220: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
a230: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
a240: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
a250: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a260: 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
a270: 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
a280: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
a290: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
a2a0: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
a2b0: 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
a2c0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
a2d0: 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
a2e0: 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
a2f0: 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
a300: 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73  ailure..*/.int s
a310: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a320: 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  e(void);.int sql
a330: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f  ite3_shutdown(vo
a340: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
a350: 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
a360: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  int sqlite3_os_e
a370: 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
a380: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
a390: 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
a3a0: 65 20 4c 69 62 72 61 72 79 20 7b 48 31 30 31 34  e Library {H1014
a3b0: 35 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 32  5} <S20000><S302
a3c0: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
a3d0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
a3e0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
a3f0: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
a400: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
a410: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
a420: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
a430: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
a440: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
a450: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
a460: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
a470: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
a480: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
a490: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
a4a0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
a4b0: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
a4c0: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
a4d0: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
a4e0: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
a4f0: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
a500: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
a510: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
a520: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
a530: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
a540: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
a550: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
a560: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
a570: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
a580: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
a590: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
a5a0: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
a5b0: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
a5c0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
a5d0: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
a5e0: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
a5f0: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
a600: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
a610: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
a620: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
a630: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
a640: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
a650: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
a660: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
a670: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f 74 65  down()]..** Note
a680: 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
a690: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a6a0: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
a6b0: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
a6c0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
a6d0: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
a6e0: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
a6f0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
a700: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
a710: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
a720: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
a730: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  n integer.** [SQ
a740: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
a750: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69  LETHREAD | confi
a760: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
a770: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
a780: 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
a790: 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
a7a0: 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
a7b0: 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
a7c0: 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
a7d0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
a7e0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
a7f0: 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f  INGLETHREAD | co
a800: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
a810: 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
a820: 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
a830: 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f 6e 66 69  .** When a confi
a840: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
a850: 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
a860: 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
a870: 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49   SQLITE_OK..** I
a880: 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
a890: 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
a8a0: 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
a8b0: 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
a8c0: 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
a8d0: 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
a8e0: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
a8f0: 65 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  e]..**.** The sq
a900: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
a910: 6e 74 65 72 66 61 63 65 20 69 73 20 63 6f 6e 73  nterface is cons
a920: 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
a930: 74 61 6c 20 69 6e 20 74 68 61 74 0a 2a 2a 20 6e  tal in that.** n
a940: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
a950: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
a960: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
a970: 72 65 6c 65 61 73 65 73 20 61 6e 64 20 65 78 69  releases and exi
a980: 73 74 69 6e 67 0a 2a 2a 20 63 6f 6e 66 69 67 75  sting.** configu
a990: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
a9a0: 61 79 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ay be discontinu
a9b0: 65 64 20 6f 72 20 6d 6f 64 69 66 69 65 64 2e 0a  ed or modified..
a9c0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
a9d0: 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
a9e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
a9f0: 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
aa00: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
aa10: 20 20 7b 48 31 30 31 38 30 7d 20 3c 53 32 30 30    {H10180} <S200
aa20: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
aa30: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
aa40: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
aa50: 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66  sed to make conf
aa60: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
aa70: 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62  nges to a [datab
aa80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
aa90: 20 20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65    .*/.int sqlite
aaa0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
aab0: 74 65 33 2a 2c 20 69 6e 74 2c 20 2e 2e 2e 29 3b  te3*, int, ...);
aac0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
aad0: 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
aae0: 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31  ion Routines {H1
aaf0: 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e 0a 2a  0155} <S20120>.*
ab00: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
ab10: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
ab20: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
ab30: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
ab40: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
ab50: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
ab60: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
ab70: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
ab80: 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
ab90: 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
aba0: 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
abb0: 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
abc0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
abd0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
abe0: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
abf0: 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
ac00: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
ac10: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
ac20: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
ac30: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
ac40: 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 61 74  LLOC].  By creat
ac50: 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
ac60: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
ac70: 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
ac80: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
ac90: 66 69 67 28 29 5d 20 64 75 72 69 6e 67 20 63 6f  fig()] during co
aca0: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 0a  nfiguration, an.
acb0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  ** application c
acc0: 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
acd0: 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
ace0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
acf0: 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 51 4c  ystem.** for SQL
ad00: 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
ad10: 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
ad20: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
ad30: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
ad40: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
ad50: 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  h a built-in mem
ad60: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
ad70: 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65 63 74  at is.** perfect
ad80: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
ad90: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
ada0: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
adb0: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
adc0: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
add0: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
ade0: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
adf0: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
ae00: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
ae10: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
ae20: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
ae30: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
ae40: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
ae50: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
ae60: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
ae70: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
ae80: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
ae90: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
aea0: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
aeb0: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
aec0: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
aed0: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
aee0: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
aef0: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
af00: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
af10: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
af20: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
af30: 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61 6e 64  lloc, xFree, and
af40: 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64   xRealloc method
af50: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
af60: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
af70: 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20 72 65  , free(), and re
af80: 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e  alloc() function
af90: 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
afa0: 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  ard library..**.
afb0: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
afc0: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
afd0: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
afe0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
aff0: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
b000: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
b010: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
b020: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
b030: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
b040: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
b050: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
b060: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
b070: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
b080: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
b090: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
b0a0: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
b0b0: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
b0c0: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
b0d0: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
b0e0: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
b0f0: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
b100: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
b110: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
b120: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b130: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
b140: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
b150: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
b160: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
b170: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
b180: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
b190: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a   power of 2..**.
b1a0: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
b1b0: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
b1c0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
b1d0: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
b1e0: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
b1f0: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
b200: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
b210: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
b220: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
b230: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
b240: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
b250: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
b260: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
b270: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b280: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
b290: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
b2a0: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
b2b0: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
b2c0: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
b2d0: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
b2e0: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
b2f0: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
b300: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79  xShutdown..*/.ty
b310: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
b320: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
b330: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
b340: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
b350: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
b360: 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
b370: 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
b380: 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
b390: 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
b3a0: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
b3b0: 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
b3c0: 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
b3d0: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
b3e0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
b3f0: 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
b400: 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
b410: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
b420: 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
b430: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
b440: 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
b450: 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
b460: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
b470: 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
b480: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
b490: 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
b4a0: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
b4b0: 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
b4c0: 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
b4d0: 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
b4e0: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
b4f0: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
b500: 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
b510: 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
b520: 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
b530: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
b540: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
b550: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
b560: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
b570: 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
b580: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
b590: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
b5a0: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
b5b0: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31  tion Options {H1
b5c0: 30 31 36 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  0160} <S20000>.*
b5d0: 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
b5e0: 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
b5f0: 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
b600: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
b610: 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
b620: 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
b630: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
b640: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
b650: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
b660: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
b670: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
b680: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
b690: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
b6a0: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
b6b0: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
b6c0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
b6d0: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
b6e0: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
b6f0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
b700: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
b710: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
b720: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
b730: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
b740: 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
b750: 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
b760: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
b770: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
b780: 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
b790: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
b7a0: 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
b7b0: 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
b7c0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
b7d0: 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
b7e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
b7f0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
b800: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
b810: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
b820: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
b830: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
b840: 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e  on.  This option
b850: 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c   disables.** all
b860: 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75   mutexing and pu
b870: 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61  ts SQLite into a
b880: 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63   mode where it c
b890: 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a  an only be used.
b8a0: 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ** by a single t
b8b0: 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  hread.</dd>.**.*
b8c0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
b8d0: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
b8e0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
b8f0: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
b900: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
b910: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  n.  This option 
b920: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
b930: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
b940: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
b950: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
b960: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
b970: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
b980: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
b990: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
b9a0: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
b9b0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
b9c0: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
b9d0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
b9e0: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
b9f0: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
ba00: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
ba10: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
ba20: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
ba30: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
ba40: 69 72 6f 6e 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a  ironment.</dd>.*
ba50: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
ba60: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
ba70: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
ba80: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
ba90: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
baa0: 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f  ion.  This optio
bab0: 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
bac0: 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
bad0: 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
bae0: 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
baf0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
bb00: 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
bb10: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
bb20: 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
bb30: 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
bb40: 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
bb50: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
bb60: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
bb70: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
bb80: 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
bb90: 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
bba0: 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
bbb0: 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
bbc0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
bbd0: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
bbe0: 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
bbf0: 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
bc00: 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
bc10: 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
bc20: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
bc30: 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
bc40: 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
bc50: 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
bc60: 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
bc70: 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
bc80: 2a 0a 2a 2a 20 3c 70 3e 54 68 69 73 20 63 6f 6e  *.** <p>This con
bc90: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
bca0: 6e 20 6d 65 72 65 6c 79 20 73 65 74 73 20 74 68  n merely sets th
bcb0: 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
bcc0: 0a 2a 2a 20 62 65 68 61 76 69 6f 72 20 74 6f 20  .** behavior to 
bcd0: 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
bce0: 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f   to [database co
bcf0: 6e 6e 65 63 74 69 6f 6e 73 5d 2e 20 20 49 6e 64  nnections].  Ind
bd00: 69 76 69 64 75 61 6c 0a 2a 2a 20 5b 64 61 74 61  ividual.** [data
bd10: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
bd20: 5d 20 63 61 6e 20 6f 76 65 72 72 69 64 65 20 74  ] can override t
bd30: 68 69 73 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75  his setting.** u
bd40: 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
bd50: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
bd60: 6c 61 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lag to [sqlite3_
bd70: 6f 70 65 6e 5f 76 32 28 29 5d 2e 3c 2f 70 3e 3c  open_v2()].</p><
bd80: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
bd90: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
bda0: 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
bdb0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
bdc0: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
bdd0: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
bde0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
bdf0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
be00: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
be10: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
be20: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
be30: 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
be40: 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
be50: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
be60: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
be70: 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
be80: 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
be90: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
bea0: 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
beb0: 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a   SQLite.</dd>.**
bec0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
bed0: 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c  ONFIG_GETMALLOC<
bee0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
bef0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
bf00: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
bf10: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
bf20: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
bf30: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
bf40: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
bf50: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
bf60: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
bf70: 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
bf80: 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
bf90: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
bfa0: 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
bfb0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
bfc0: 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70  ines..** This op
bfd0: 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
bfe0: 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
bff0: 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
c000: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
c010: 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
c020: 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c  apper that simul
c030: 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c  ations memory al
c040: 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
c050: 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65   or.** tracks me
c060: 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20  mory usage, for 
c070: 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a  example.</dd>.**
c080: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
c090: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
c0a0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
c0b0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
c0c0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
c0d0: 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
c0e0: 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
c0f0: 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
c100: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
c110: 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
c120: 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
c130: 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
c140: 73 74 69 63 73 2e 20 57 68 65 6e 20 64 69 73 61  stics. When disa
c150: 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77  bled, the follow
c160: 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
c170: 66 61 63 65 73 20 62 65 63 6f 6d 65 20 0a 2a 2a  faces become .**
c180: 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
c190: 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
c1a0: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
c1b0: 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
c1c0: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
c1d0: 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
c1e0: 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
c1f0: 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
c200: 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20  p_limit()].**   
c210: 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 6d 65 6d  <li> sqlite3_mem
c220: 6f 72 79 5f 73 74 61 74 75 73 28 29 0a 2a 2a 20  ory_status().** 
c230: 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e    </ul>.** </dd>
c240: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
c250: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
c260: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
c270: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
c280: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
c290: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
c2a0: 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
c2b0: 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  r.** scratch mem
c2c0: 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20  ory.  There are 
c2d0: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
c2e0: 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74    A pointer to t
c2f0: 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 0a 2a  he memory, the.*
c300: 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73  * size of each s
c310: 63 72 61 74 63 68 20 62 75 66 66 65 72 20 28 73  cratch buffer (s
c320: 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62  z), and the numb
c330: 65 72 20 6f 66 20 62 75 66 66 65 72 73 20 28 4e  er of buffers (N
c340: 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72  ).  The sz.** ar
c350: 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
c360: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e   multiple of 16.
c370: 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72   The first.** ar
c380: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f  gument should po
c390: 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61  int to an alloca
c3a0: 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74  tion of at least
c3b0: 20 28 73 7a 2b 34 29 2a 4e 20 62 79 74 65 73 20   (sz+4)*N bytes 
c3c0: 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51  of memory..** SQ
c3d0: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f  Lite will use no
c3e0: 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73   more than one s
c3f0: 63 72 61 74 63 68 20 62 75 66 66 65 72 20 61 74  cratch buffer at
c400: 20 6f 6e 63 65 20 70 65 72 20 74 68 72 65 61 64   once per thread
c410: 2c 20 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64  , so.** N should
c420: 20 62 65 20 73 65 74 20 74 6f 20 74 68 65 20 65   be set to the e
c430: 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20  xpected maximum 
c440: 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64  number of thread
c450: 73 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 70 61  s.  The sz.** pa
c460: 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62  rameter should b
c470: 65 20 36 20 74 69 6d 65 73 20 74 68 65 20 73 69  e 6 times the si
c480: 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
c490: 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  t database page 
c4a0: 73 69 7a 65 2e 0a 2a 2a 20 53 63 72 61 74 63 68  size..** Scratch
c4b0: 20 62 75 66 66 65 72 73 20 61 72 65 20 75 73 65   buffers are use
c4c0: 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
c4d0: 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 20 6f   btree balance o
c4e0: 70 65 72 61 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a  peration.  If.**
c4f0: 20 54 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e   The btree balan
c500: 63 65 72 20 6e 65 65 64 73 20 61 64 64 69 74 69  cer needs additi
c510: 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 62 65 79 6f  onal memory beyo
c520: 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
c530: 64 65 64 20 62 79 0a 2a 2a 20 73 63 72 61 74 63  ded by.** scratc
c540: 68 20 62 75 66 66 65 72 73 20 6f 72 20 69 66 20  h buffers or if 
c550: 6e 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65  no scratch buffe
c560: 72 20 73 70 61 63 65 20 69 73 20 73 70 65 63 69  r space is speci
c570: 66 69 65 64 2c 20 74 68 65 6e 20 53 51 4c 69 74  fied, then SQLit
c580: 65 0a 2a 2a 20 67 6f 65 73 20 74 6f 20 5b 73 71  e.** goes to [sq
c590: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
c5a0: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65  to obtain the me
c5b0: 6d 6f 72 79 20 69 74 20 6e 65 65 64 73 2e 3c 2f  mory it needs.</
c5c0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
c5d0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
c5e0: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
c5f0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70  d>This option sp
c600: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
c610: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
c620: 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
c630: 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61  se for.** the da
c640: 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
c650: 65 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68  e.  There are th
c660: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41  ree arguments: A
c670: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
c680: 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73  ** memory, the s
c690: 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65  ize of each page
c6a0: 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e   buffer (sz), an
c6b0: 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
c6c0: 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  pages (N)..** Th
c6d0: 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 6d 75  e sz argument mu
c6e0: 73 74 20 62 65 20 61 20 70 6f 77 65 72 20 6f 66  st be a power of
c6f0: 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
c700: 20 61 6e 64 20 33 32 37 36 38 2e 20 20 54 68 65   and 32768.  The
c710: 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65   first.** argume
c720: 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20  nt should point 
c730: 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  to an allocation
c740: 20 6f 66 20 61 74 20 6c 65 61 73 74 20 28 73 7a   of at least (sz
c750: 2b 34 29 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d  +4)*N bytes of m
c760: 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65  emory..** SQLite
c770: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65   will use the me
c780: 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79  mory provided by
c790: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
c7a0: 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69  ent to satisfy i
c7b0: 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65  ts.** memory nee
c7c0: 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  ds for the first
c7d0: 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74   N pages that it
c7e0: 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20   adds to cache. 
c7f0: 20 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a   If additional.*
c800: 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
c810: 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
c820: 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
c830: 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
c840: 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
c850: 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
c860: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
c870: 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
c880: 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
c890: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
c8a0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  >SQLITE_CONFIG_H
c8b0: 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAP</dt>.** <dd>
c8c0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
c8d0: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
c8e0: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
c8f0: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  t SQLite will us
c900: 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20  e.** for all of 
c910: 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
c920: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
c930: 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65  eds beyond those
c940: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72   provided.** for
c950: 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
c960: 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20  IG_SCRATCH] and 
c970: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
c980: 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68  AGECACHE]..** Th
c990: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
c9a0: 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74  guments: A point
c9b0: 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
c9c0: 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  , the number of.
c9d0: 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
c9e0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
c9f0: 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
ca00: 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 20  llocation size. 
ca10: 20 49 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   If.** the first
ca20: 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
ca30: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
ca40: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
ca50: 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
ca60: 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
ca70: 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
ca80: 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
ca90: 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
caa0: 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
cab0: 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
cac0: 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
cad0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
cae0: 4f 43 5d 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20  OC].  If the.** 
caf0: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
cb00: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65  s not NULL and e
cb10: 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
cb20: 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
cb30: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
cb40: 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20  LE_MEMSYS5] are 
cb50: 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68  defined, then th
cb60: 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
cb70: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
cb80: 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
cb90: 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
cba0: 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
cbb0: 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 3c 2f  ocation needs.</
cbc0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
cbd0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
cbe0: 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  X</dt>.** <dd>Th
cbf0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
cc00: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
cc10: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
cc20: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
cc30: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
cc40: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
cc50: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
cc60: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
cc70: 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
cc80: 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
cc90: 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
cca0: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
ccb0: 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lace.** the mute
ccc0: 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
ccd0: 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64   into SQLite.</d
cce0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
ccf0: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
cd00: 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
cd10: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
cd20: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
cd30: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
cd40: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
cd50: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
cd60: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
cd70: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
cd80: 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
cd90: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
cda0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
cdb0: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
cdc0: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
cdd0: 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
cde0: 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  nes..** This opt
cdf0: 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
ce00: 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
ce10: 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
ce20: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
ce30: 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
ce40: 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
ce50: 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
ce60: 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
ce70: 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
ce80: 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
ce90: 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  le.</dd>.**.** <
cea0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
ceb0: 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
cec0: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
ced0: 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
cee0: 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
cef0: 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c  rmine the defaul
cf00: 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 63  t.** memory allc
cf10: 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69 64 65 20  ation lookaside 
cf20: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 20 54  optimization.  T
cf30: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
cf40: 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
cf50: 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
cf60: 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
cf70: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
cf80: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
cf90: 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
cfa0: 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
cfb0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 3c 2f  se connection.</
cfc0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
cfd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
cfe0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
cff0: 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
d000: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d010: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
d020: 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
d030: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
d040: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
d050: 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
d060: 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
d070: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
d080: 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
d090: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
d0a0: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
d0b0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
d0c0: 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
d0d0: 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
d0e0: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
d0f0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d100: 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
d110: 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
d120: 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
d130: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
d140: 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
d150: 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
d160: 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
d170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
d180: 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
d190: 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
d1a0: 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
d1b0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
d1c0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
d1d0: 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
d1e0: 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
d1f0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d200: 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
d210: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
d220: 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
d230: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
d240: 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
d250: 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
d260: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
d270: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d280: 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
d290: 4f 43 20 20 20 31 32 20 20 2f 2a 20 69 6e 74 20  OC   12  /* int 
d2a0: 74 68 72 65 73 68 6f 6c 64 20 2a 2f 0a 23 64 65  threshold */.#de
d2b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
d2c0: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
d2d0: 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
d2e0: 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
d2f0: 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
d300: 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
d310: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 32  esult Codes {H12
d320: 32 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  200} <S10700>.**
d330: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
d340: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
d350: 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
d360: 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
d370: 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
d380: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
d390: 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
d3a0: 4c 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e 64  Lite. The extend
d3b0: 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
d3c0: 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
d3d0: 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
d3e0: 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
d3f0: 69 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 72  ibility consider
d400: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ations..**.** IN
d410: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
d420: 7b 48 31 32 32 30 31 7d 20 45 61 63 68 20 6e 65  {H12201} Each ne
d430: 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  w [database conn
d440: 65 63 74 69 6f 6e 5d 20 73 68 61 6c 6c 20 68 61  ection] shall ha
d450: 76 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ve the.**       
d460: 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73     [extended res
d470: 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
d480: 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
d490: 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  efault..**.** {H
d4a0: 31 32 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69  12202} The [sqli
d4b0: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
d4c0: 75 6c 74 5f 63 6f 64 65 73 28 44 2c 46 29 5d 20  ult_codes(D,F)] 
d4d0: 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
d4e0: 65 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20  enable.**       
d4f0: 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73     [extended res
d500: 75 6c 74 20 63 6f 64 65 73 5d 20 66 6f 72 20 74  ult codes] for t
d510: 68 65 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f  he  [database co
d520: 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20  nnection] D.**  
d530: 20 20 20 20 20 20 20 20 69 66 20 74 68 65 20 46          if the F
d540: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 72   parameter is tr
d550: 75 65 2c 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ue, or disable t
d560: 68 65 6d 20 69 66 20 46 20 69 73 20 66 61 6c 73  hem if F is fals
d570: 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
d580: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
d590: 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
d5a0: 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
d5b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
d5c0: 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
d5d0: 20 7b 48 31 32 32 32 30 7d 20 3c 53 31 30 37 30   {H12220} <S1070
d5e0: 30 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e  0>.**.** Each en
d5f0: 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65  try in an SQLite
d600: 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69   table has a uni
d610: 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  que 64-bit signe
d620: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79  d.** integer key
d630: 20 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77   called the "row
d640: 69 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69  id". The rowid i
d650: 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62  s always availab
d660: 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65  le.** as an unde
d670: 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61  clared column na
d680: 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20  med ROWID, OID, 
d690: 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f  or _ROWID_ as lo
d6a0: 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e  ng as those.** n
d6b0: 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73  ames are not als
d6c0: 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63  o used by explic
d6d0: 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
d6e0: 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65  lumns. If.** the
d6f0: 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
d700: 75 6d 6e 20 6f 66 20 74 79 70 65 20 49 4e 54 45  umn of type INTE
d710: 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20  GER PRIMARY KEY 
d720: 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
d730: 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
d740: 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
d750: 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  id..**.** This r
d760: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
d770: 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20  he rowid of the 
d780: 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
d790: 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54  uccessful INSERT
d7a0: 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
d7b0: 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74  se from the [dat
d7c0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d7d0: 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
d7e0: 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20  t argument.  If 
d7f0: 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e  no successful IN
d800: 53 45 52 54 73 0a 2a 2a 20 68 61 76 65 20 65 76  SERTs.** have ev
d810: 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
d820: 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e  hat database con
d830: 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73  nection, zero is
d840: 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
d850: 20 49 66 20 61 6e 20 49 4e 53 45 52 54 20 6f 63   If an INSERT oc
d860: 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
d870: 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20  igger, then the 
d880: 72 6f 77 69 64 20 6f 66 20 74 68 65 20 69 6e 73  rowid of the ins
d890: 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20  erted.** row is 
d8a0: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
d8b0: 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67   routine as long
d8c0: 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
d8d0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42  is running..** B
d8e0: 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67  ut once the trig
d8f0: 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20  ger terminates, 
d900: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
d910: 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ed by this routi
d920: 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f  ne.** reverts to
d930: 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20   the last value 
d940: 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65 20  inserted before 
d950: 74 68 65 20 74 72 69 67 67 65 72 20 66 69 72 65  the trigger fire
d960: 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 49 4e 53 45  d..**.** An INSE
d970: 52 54 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  RT that fails du
d980: 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
d990: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
d9a0: 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
d9b0: 75 6c 20 49 4e 53 45 52 54 20 61 6e 64 20 64 6f  ul INSERT and do
d9c0: 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
d9d0: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
d9e0: 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
d9f0: 69 6e 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52  ine.  Thus INSER
da00: 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
da10: 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
da20: 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
da30: 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
da40: 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
da50: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
da60: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
da70: 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
da80: 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
da90: 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e  ion fails.  When
daa0: 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
dab0: 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
dac0: 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
dad0: 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
dae0: 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
daf0: 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
db00: 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
db10: 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
db20: 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
db30: 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
db40: 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
db50: 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
db60: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
db70: 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
db80: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
db90: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
dba0: 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65   For the purpose
dbb0: 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
dbc0: 65 2c 20 61 6e 20 49 4e 53 45 52 54 20 69 73 20  e, an INSERT is 
dbd0: 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
dbe0: 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
dbf0: 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
dc00: 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
dc10: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   back..**.** INV
dc20: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
dc30: 48 31 32 32 32 31 7d 20 54 68 65 20 5b 73 71 6c  H12221} The [sql
dc40: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
dc50: 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69  _rowid()] functi
dc60: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 72  on returns the r
dc70: 6f 77 69 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  owid.**         
dc80: 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   of the most rec
dc90: 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 49  ent successful I
dca0: 4e 53 45 52 54 20 70 65 72 66 6f 72 6d 65 64 20  NSERT performed 
dcb0: 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  on the same.**  
dcc0: 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
dcd0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
dce0: 64 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  d within the sam
dcf0: 65 20 6f 72 20 68 69 67 68 65 72 20 6c 65 76 65  e or higher leve
dd00: 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 72  l.**          tr
dd10: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f  igger context, o
dd20: 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20  r zero if there 
dd30: 68 61 76 65 20 62 65 65 6e 20 6e 6f 20 71 75 61  have been no qua
dd40: 6c 69 66 79 69 6e 67 20 69 6e 73 65 72 74 73 2e  lifying inserts.
dd50: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32 33 7d 20  .**.** {H12223} 
dd60: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  The [sqlite3_las
dd70: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
dd80: 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ] function retur
dd90: 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
dda0: 20 20 20 73 61 6d 65 20 76 61 6c 75 65 20 77 68     same value wh
ddb0: 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
ddc0: 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 20  he same trigger 
ddd0: 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20 20 20  context.**      
dde0: 20 20 20 20 69 6d 6d 65 64 69 61 74 65 6c 79 20      immediately 
ddf0: 62 65 66 6f 72 65 20 61 6e 64 20 61 66 74 65 72  before and after
de00: 20 61 20 52 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a   a ROLLBACK..**.
de10: 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
de20: 2a 2a 0a 2a 2a 20 7b 41 31 32 32 33 32 7d 20 49  **.** {A12232} I
de30: 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
de40: 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
de50: 65 77 20 49 4e 53 45 52 54 20 6f 6e 20 74 68 65  ew INSERT on the
de60: 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   same.**        
de70: 20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65    database conne
de80: 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
de90: 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
dea0: 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
deb0: 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69            functi
dec0: 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
ded0: 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
dee0: 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72  he last insert r
def0: 6f 77 69 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  owid,.**        
df00: 20 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65    then the value
df10: 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
df20: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
df30: 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
df40: 20 20 20 20 20 20 20 20 20 20 75 6e 70 72 65 64            unpred
df50: 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
df60: 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
df70: 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
df80: 65 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20  e new.**        
df90: 20 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f    last insert ro
dfa0: 77 69 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  wid..*/.sqlite3_
dfb0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
dfc0: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
dfd0: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
dfe0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
dff0: 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
e000: 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48  Rows Modified {H
e010: 31 32 32 34 30 7d 20 3c 53 31 30 36 30 30 3e 0a  12240} <S10600>.
e020: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
e030: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
e040: 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
e050: 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
e060: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20  e changed.** or 
e070: 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
e080: 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
e090: 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
e0a0: 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
e0b0: 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  .** on the [data
e0c0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
e0d0: 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
e0e0: 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
e0f0: 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68 61 6e 67  r..** Only chang
e100: 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65  es that are dire
e110: 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62  ctly specified b
e120: 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50  y the INSERT, UP
e130: 44 41 54 45 2c 0a 2a 2a 20 6f 72 20 44 45 4c 45  DATE,.** or DELE
e140: 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  TE statement are
e150: 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
e160: 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
e170: 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
e180: 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  rs are not count
e190: 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c  ed. Use the [sql
e1a0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
e1b0: 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a  es()] function.*
e1c0: 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  * to find the to
e1d0: 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
e1e0: 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  anges including 
e1f0: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
e200: 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a  y triggers..**.*
e210: 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  * A "row change"
e220: 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
e230: 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
e240: 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
e250: 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
e260: 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
e270: 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
e280: 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
e290: 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
e2a0: 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
e2b0: 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
e2c0: 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a  int resolution,.
e2d0: 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f  ** rollback, ABO
e2e0: 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 44  RT processing, D
e2f0: 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72 20 62 79  ROP TABLE, or by
e300: 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   any other.** me
e310: 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20  chanisms do not 
e320: 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20  count as direct 
e330: 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a  row changes..**.
e340: 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f  ** A "trigger co
e350: 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70  ntext" is a scop
e360: 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74  e of execution t
e370: 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a  hat begins and.*
e380: 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20  * ends with the 
e390: 73 63 72 69 70 74 20 6f 66 20 61 20 74 72 69 67  script of a trig
e3a0: 67 65 72 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73  ger.  Most SQL s
e3b0: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
e3c0: 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69   evaluated outsi
e3d0: 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65  de of any trigge
e3e0: 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20  r.  This is the 
e3f0: 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74  "top level".** t
e400: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20  rigger context. 
e410: 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69   If a trigger fi
e420: 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  res from the top
e430: 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77   level, a.** new
e440: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
e450: 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20   is entered for 
e460: 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20  the duration of 
e470: 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67  that one.** trig
e480: 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72  ger.  Subtrigger
e490: 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74  s create subcont
e4a0: 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64  exts for their d
e4b0: 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43  uration..**.** C
e4c0: 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
e4d0: 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  exec()] or [sqli
e4e0: 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75  te3_step()] recu
e4f0: 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20  rsively does.** 
e500: 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77  not create a new
e510: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
e520: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
e530: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
e540: 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65  e number of dire
e550: 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69  ct row changes i
e560: 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65  n the.** most re
e570: 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
e580: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73  ATE, or DELETE s
e590: 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
e5a0: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67  the same.** trig
e5b0: 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
e5c0: 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e 20 63 61  ** Thus, when ca
e5d0: 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
e5e0: 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
e5f0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
e600: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
e610: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
e620: 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
e630: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
e640: 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
e650: 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
e660: 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69  e top level.  Wi
e670: 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
e680: 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
e690: 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
e6a0: 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
e6b0: 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
e6c0: 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
e6d0: 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
e6e0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
e6f0: 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
e700: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
e710: 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
e720: 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
e730: 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
e740: 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
e750: 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
e760: 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
e770: 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
e780: 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
e790: 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
e7a0: 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
e7b0: 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a  r own context..*
e7c0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c  *.** SQLite impl
e7d0: 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61  ements the comma
e7e0: 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  nd "DELETE FROM 
e7f0: 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61  table" without a
e800: 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a   WHERE clause.**
e810: 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64   by dropping and
e820: 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20   recreating the 
e830: 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73  table.  (This is
e840: 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61   much faster tha
e850: 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75  n going.** throu
e860: 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20  gh and deleting 
e870: 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65  individual eleme
e880: 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62  nts from the tab
e890: 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66  le.)  Because of
e8a0: 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a   this.** optimiz
e8b0: 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74  ation, the delet
e8c0: 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20  ions in "DELETE 
e8d0: 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20  FROM table" are 
e8e0: 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  not row changes 
e8f0: 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  and.** will not 
e900: 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68  be counted by th
e910: 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
e920: 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  s() or [sqlite3_
e930: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
e940: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72  .** functions, r
e950: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
e960: 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65   number of eleme
e970: 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72  nts that were or
e980: 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74  iginally.** in t
e990: 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65  he table.  To ge
e9a0: 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f  t an accurate co
e9b0: 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  unt of the numbe
e9c0: 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65  r of rows delete
e9d0: 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54  d, use.** "DELET
e9e0: 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45  E FROM table WHE
e9f0: 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a  RE 1" instead..*
ea00: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
ea10: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 31 7d 20  .**.** {H12241} 
ea20: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  The [sqlite3_cha
ea30: 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
ea40: 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 74 68   shall return th
ea50: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20  e number of.**  
ea60: 20 20 20 20 20 20 20 20 72 6f 77 20 63 68 61 6e          row chan
ea70: 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 68  ges caused by th
ea80: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
ea90: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a  SERT, UPDATE,.**
eaa0: 20 20 20 20 20 20 20 20 20 20 6f 72 20 44 45 4c            or DEL
eab0: 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e  ETE statement on
eac0: 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
ead0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e  se connection an
eae0: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  d.**          wi
eaf0: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  thin the same or
eb00: 20 68 69 67 68 65 72 20 74 72 69 67 67 65 72 20   higher trigger 
eb10: 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f  context, or zero
eb20: 20 69 66 20 74 68 65 72 65 20 68 61 76 65 0a 2a   if there have.*
eb30: 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 62  *          not b
eb40: 65 65 6e 20 61 6e 79 20 71 75 61 6c 69 66 79 69  een any qualifyi
eb50: 6e 67 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a  ng row changes..
eb60: 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 33 7d 20 53  **.** {H12243} S
eb70: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74 68 65  tatements of the
eb80: 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20 46 52   form "DELETE FR
eb90: 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20 77 69  OM tablename" wi
eba0: 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20  th no.**        
ebb0: 20 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 73    WHERE clause s
ebc0: 68 61 6c 6c 20 63 61 75 73 65 20 73 75 62 73 65  hall cause subse
ebd0: 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
ebe0: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
ebf0: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 74  te3_changes()] t
ec00: 6f 20 72 65 74 75 72 6e 20 7a 65 72 6f 2c 20 72  o return zero, r
ec10: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
ec20: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
ec30: 62 65 72 20 6f 66 20 72 6f 77 73 20 6f 72 69 67  ber of rows orig
ec40: 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 20 74 61  inally in the ta
ec50: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  ble..**.** ASSUM
ec60: 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
ec70: 31 32 32 35 32 7d 20 49 66 20 61 20 73 65 70 61  12252} If a sepa
ec80: 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
ec90: 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
eca0: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
ecb0: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  onnection.**    
ecc0: 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c        while [sql
ecd0: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
ece0: 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
ecf0: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
ed00: 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ed.**          i
ed10: 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
ed20: 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
ed30: 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
ed40: 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
ed50: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
ed60: 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
ed70: 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
ed80: 66 69 65 64 20 7b 48 31 32 32 36 30 7d 20 3c 53  fied {H12260} <S
ed90: 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  10600>.**.** Thi
eda0: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
edb0: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
edc0: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
edd0: 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c 0a 2a  sed by INSERT,.*
ede0: 2a 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  * UPDATE or DELE
edf0: 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69  TE statements si
ee00: 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73  nce the [databas
ee10: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61  e connection] wa
ee20: 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65  s opened..** The
ee30: 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73 20   count includes 
ee40: 61 6c 6c 20 63 68 61 6e 67 65 73 20 66 72 6f 6d  all changes from
ee50: 20 61 6c 6c 20 74 72 69 67 67 65 72 20 63 6f 6e   all trigger con
ee60: 74 65 78 74 73 2e 20 20 48 6f 77 65 76 65 72 2c  texts.  However,
ee70: 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f  .** the count do
ee80: 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
ee90: 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69  hanges used to i
eea0: 6d 70 6c 65 6d 65 6e 74 20 52 45 50 4c 41 43 45  mplement REPLACE
eeb0: 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a   constraints,.**
eec0: 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72   do rollbacks or
eed0: 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
eee0: 67 2c 20 6f 72 20 44 52 4f 50 20 74 61 62 6c 65  g, or DROP table
eef0: 20 70 72 6f 63 65 73 73 69 6e 67 2e 0a 2a 2a 20   processing..** 
ef00: 54 68 65 20 63 68 61 6e 67 65 73 20 61 72 65 20  The changes are 
ef10: 63 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20  counted as soon 
ef20: 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
ef30: 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d   that makes them
ef40: 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64   is.** completed
ef50: 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65   (when the state
ef60: 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 73 20 70  ment handle is p
ef70: 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
ef80: 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
ef90: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
efa0: 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51  ze()])..**.** SQ
efb0: 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
efc0: 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c  the command "DEL
efd0: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
efe0: 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20  without a WHERE 
eff0: 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f  clause.** by dro
f000: 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61  pping and recrea
f010: 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20  ting the table. 
f020: 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66   (This is much f
f030: 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67  aster than going
f040: 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20  .** through and 
f050: 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64  deleting individ
f060: 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f  ual elements fro
f070: 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42  m the table.)  B
f080: 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a  ecause of this.*
f090: 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20  * optimization, 
f0a0: 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e  the deletions in
f0b0: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
f0c0: 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77  ble" are not row
f0d0: 20 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20   changes and.** 
f0e0: 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e  will not be coun
f0f0: 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
f100: 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20  e3_changes() or 
f110: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
f120: 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e  hanges()].** fun
f130: 63 74 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65  ctions, regardle
f140: 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ss of the number
f150: 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61   of elements tha
f160: 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c  t were originall
f170: 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61 62 6c  y.** in the tabl
f180: 65 2e 20 20 54 6f 20 67 65 74 20 61 6e 20 61 63  e.  To get an ac
f190: 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20  curate count of 
f1a0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
f1b0: 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a  ws deleted, use.
f1c0: 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  ** "DELETE FROM 
f1d0: 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69  table WHERE 1" i
f1e0: 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  nstead..**.** Se
f1f0: 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
f200: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
f210: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
f220: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
f230: 2a 20 7b 48 31 32 32 36 31 7d 20 54 68 65 20 5b  * {H12261} The [
f240: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
f250: 61 6e 67 65 73 28 29 5d 20 72 65 74 75 72 6e 73  anges()] returns
f260: 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
f270: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  r.**          of
f280: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
f290: 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c 20 55  sed by INSERT, U
f2a0: 50 44 41 54 45 2c 20 61 6e 64 2f 6f 72 20 44 45  PDATE, and/or DE
f2b0: 4c 45 54 45 0a 2a 2a 20 20 20 20 20 20 20 20 20  LETE.**         
f2c0: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 74   statements on t
f2d0: 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
f2e0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 69  e connection], i
f2f0: 6e 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 20 20  n any.**        
f300: 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78    trigger contex
f310: 74 2c 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  t, since the dat
f320: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f330: 20 77 61 73 20 63 72 65 61 74 65 64 2e 0a 2a 2a   was created..**
f340: 0a 2a 2a 20 7b 48 31 32 32 36 33 7d 20 53 74 61  .** {H12263} Sta
f350: 74 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66  tements of the f
f360: 6f 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  orm "DELETE FROM
f370: 20 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68   tablename" with
f380: 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   no.**          
f390: 57 48 45 52 45 20 63 6c 61 75 73 65 20 73 68 61  WHERE clause sha
f3a0: 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  ll not change th
f3b0: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
f3c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20  .**          by 
f3d0: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
f3e0: 68 61 6e 67 65 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a  hanges()]..**.**
f3f0: 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a   ASSUMPTIONS:.**
f400: 0a 2a 2a 20 7b 41 31 32 32 36 34 7d 20 49 66 20  .** {A12264} If 
f410: 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
f420: 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
f430: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
f440: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
f450: 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 6c  **          whil
f460: 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
f470: 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
f480: 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
f490: 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20  value.**        
f4a0: 20 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e    returned is un
f4b0: 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
f4c0: 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
f4d0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
f4e0: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
f4f0: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
f500: 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
f510: 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
f520: 67 20 51 75 65 72 79 20 7b 48 31 32 32 37 30 7d  g Query {H12270}
f530: 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S30500>.**.** 
f540: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
f550: 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
f560: 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
f570: 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
f580: 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
f590: 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
f5a0: 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
f5b0: 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
f5c0: 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
f5d0: 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
f5e0: 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
f5f0: 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
f600: 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
f610: 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
f620: 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
f630: 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
f640: 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
f650: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ly..**.** It is 
f660: 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
f670: 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
f680: 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
f690: 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
f6a0: 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
f6b0: 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
f6c0: 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
f6d0: 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
f6e0: 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
f6f0: 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
f700: 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
f710: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
f720: 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
f730: 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
f740: 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
f750: 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
f760: 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  rns..**.** If an
f770: 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
f780: 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
f790: 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
f7a0: 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
f7b0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
f7c0: 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
f7d0: 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
f7e0: 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
f7f0: 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
f800: 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
f810: 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
f820: 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  etion..**.** An 
f830: 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
f840: 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
f850: 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
f860: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
f870: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74 65  ..** If the inte
f880: 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
f890: 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
f8a0: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
f8b0: 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
f8c0: 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
f8d0: 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
f8e0: 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
f8f0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
f900: 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
f910: 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
f920: 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  y..**.** A call 
f930: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
f940: 72 75 70 74 28 29 20 68 61 73 20 6e 6f 20 65 66  rupt() has no ef
f950: 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
f960: 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
f970: 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
f980: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
f990: 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
f9a0: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
f9b0: 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 31 7d 20 54  **.** {H12271} T
f9c0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  he [sqlite3_inte
f9d0: 72 72 75 70 74 28 29 5d 20 69 6e 74 65 72 66 61  rrupt()] interfa
f9e0: 63 65 20 77 69 6c 6c 20 66 6f 72 63 65 20 61 6c  ce will force al
f9f0: 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20  l running.**    
fa00: 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d        SQL statem
fa10: 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
fa20: 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 64 61  with the same da
fa30: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
fa40: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  n.**          to
fa50: 20 68 61 6c 74 20 61 66 74 65 72 20 70 72 6f 63   halt after proc
fa60: 65 73 73 69 6e 67 20 61 74 20 6d 6f 73 74 20 6f  essing at most o
fa70: 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 6f  ne additional ro
fa80: 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
fa90: 20 7b 48 31 32 32 37 32 7d 20 41 6e 79 20 53 51   {H12272} Any SQ
faa0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
fab0: 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
fac0: 62 79 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  by [sqlite3_inte
fad0: 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20  rrupt()].**     
fae0: 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72 6e       will return
faf0: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
fb00: 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  PT]..**.** ASSUM
fb10: 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
fb20: 31 32 32 37 39 7d 20 49 66 20 74 68 65 20 64 61  12279} If the da
fb30: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
fb40: 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
fb50: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
fb60: 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  t()].**         
fb70: 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
fb80: 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
fb90: 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
fba0: 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
fbb0: 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
fbc0: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
fbd0: 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
fbe0: 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
fbf0: 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20  ent Is Complete 
fc00: 7b 48 31 30 35 31 30 7d 20 3c 53 37 30 32 30 30  {H10510} <S70200
fc10: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
fc20: 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
fc30: 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69  l for command-li
fc40: 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
fc50: 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
fc60: 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
fc70: 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
fc80: 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 20 61 20  form complete a 
fc90: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
fca0: 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
fcb0: 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
fcc0: 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
fcd0: 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
fce0: 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
fcf0: 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72 6f 75  sing.  These rou
fd00: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 72 75  tines return tru
fd10: 65 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  e if the input s
fd20: 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
fd30: 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
fd40: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
fd50: 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73    A statement is
fd60: 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
fd70: 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
fd80: 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
fd90: 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
fda0: 69 73 20 6e 6f 74 20 61 20 66 72 61 67 6d 65 6e  is not a fragmen
fdb0: 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45 41 54 45  t of a.** CREATE
fdc0: 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
fdd0: 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20  nt.  Semicolons 
fde0: 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65  that are embedde
fdf0: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69  d within.** stri
fe00: 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71  ng literals or q
fe10: 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72  uoted identifier
fe20: 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e   names or commen
fe30: 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e  ts are not.** in
fe40: 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73  dependent tokens
fe50: 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20   (they are part 
fe60: 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20  of the token in 
fe70: 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a  which they are.*
fe80: 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20  * embedded) and 
fe90: 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  thus do not coun
fea0: 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74  t as a statement
feb0: 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
fec0: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
fed0: 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
fee0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
fef0: 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
ff00: 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
ff10: 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
ff20: 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  t SQL..**.** INV
ff30: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
ff40: 48 31 30 35 31 31 7d 20 41 20 73 75 63 63 65 73  H10511} A succes
ff50: 73 66 75 6c 20 65 76 61 6c 75 61 74 69 6f 6e 20  sful evaluation 
ff60: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  of [sqlite3_comp
ff70: 6c 65 74 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20  lete()] or.**   
ff80: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
ff90: 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 66 75  complete16()] fu
ffa0: 6e 63 74 69 6f 6e 73 20 73 68 61 6c 6c 0a 2a 2a  nctions shall.**
ffb0: 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
ffc0: 20 61 20 6e 75 6d 65 72 69 63 20 31 20 69 66 20   a numeric 1 if 
ffd0: 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
ffe0: 6c 61 73 74 20 6e 6f 6e 2d 77 68 69 74 65 73 70  last non-whitesp
fff0: 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ace.**          
10000 74 6f 6b 65 6e 20 69 6e 20 74 68 65 69 72 20 69  token in their i
10010 6e 70 75 74 20 69 73 20 61 20 73 65 6d 69 63 6f  nput is a semico
10020 6c 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20  lon that is not 
10030 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 20 20  in between.**   
10040 20 20 20 20 20 20 20 74 68 65 20 42 45 47 49 4e         the BEGIN
10050 20 61 6e 64 20 45 4e 44 20 6f 66 20 61 20 43 52   and END of a CR
10060 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61  EATE TRIGGER sta
10070 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tement..**.** {H
10080 31 30 35 31 32 7d 20 49 66 20 61 20 6d 65 6d 6f  10512} If a memo
10090 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
100a0 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
100b0 67 20 61 6e 20 69 6e 76 6f 63 61 74 69 6f 6e 0a  g an invocation.
100c0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 5b  **          of [
100d0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
100e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
100f0 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 74 68  complete16()] th
10100 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  en the.**       
10110 20 20 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c     routine shall
10120 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
10130 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53  NOMEM]..**.** AS
10140 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
10150 20 7b 41 31 30 35 31 32 7d 20 54 68 65 20 69 6e   {A10512} The in
10160 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
10170 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
10180 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
10190 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
101a0 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a    UTF-8 string..
101b0 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 33 7d 20 54  **.** {A10513} T
101c0 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
101d0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
101e0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
101f0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
10200 20 20 20 20 20 20 20 20 20 55 54 46 2d 31 36 20           UTF-16 
10210 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
10220 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
10230 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
10240 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
10250 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
10260 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
10270 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
10280 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10290 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
102a0 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
102b0 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
102c0 73 20 7b 48 31 32 33 31 30 7d 20 3c 53 34 30 34  s {H12310} <S404
102d0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00>.**.** This r
102e0 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
102f0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
10300 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
10310 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a  voked whenever.*
10320 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
10330 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64  made to open a d
10340 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68  atabase table th
10350 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  at another threa
10360 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
10370 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a  has locked..**.*
10380 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61  * If the busy ca
10390 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
103a0 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
103b0 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
103c0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
103d0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
103e0 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
103f0 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
10400 63 6b 2e 20 49 66 20 74 68 65 20 62 75 73 79 20  ck. If the busy 
10410 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
10420 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
10430 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20  e callback will 
10440 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
10450 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
10460 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
10470 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68  rgument to the h
10480 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
10490 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
104a0 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
104b0 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
104c0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
104d0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
104e0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
104f0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68  ment to.** the h
10500 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
10510 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
10520 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
10530 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
10540 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
10550 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e   for this lockin
10560 67 20 65 76 65 6e 74 2e 20 20 49 66 20 74 68 65  g event.  If the
10570 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
10580 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
10590 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
105a0 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
105b0 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
105c0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
105d0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
105e0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
105f0 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72  LOCKED] is retur
10600 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ned..** If the c
10610 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
10620 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
10630 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
10640 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  * is made to ope
10650 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
10660 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74  or reading and t
10670 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
10680 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
10690 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
106a0 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
106b0 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
106c0 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
106d0 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
106e0 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
106f0 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 64 65  on. If SQLite de
10700 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
10710 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
10720 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
10730 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
10740 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
10750 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
10760 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
10770 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
10780 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
10790 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
107a0 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
107b0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
107c0 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
107d0 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
107e0 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
107f0 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
10800 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
10810 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
10820 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
10830 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
10840 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
10850 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
10860 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
10870 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
10880 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
10890 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
108a0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
108b0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
108c0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
108d0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
108e0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
108f0 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
10900 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
10910 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
10920 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
10930 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
10940 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
10950 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
10960 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
10970 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
10980 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
10990 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
109a0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
109b0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
109c0 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
109d0 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
109e0 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
109f0 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
10a00 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
10a10 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
10a20 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
10a30 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  **.** The defaul
10a40 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
10a50 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  is NULL..**.** T
10a60 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  he [SQLITE_BUSY]
10a70 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72   error is conver
10a80 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49  ted to [SQLITE_I
10a90 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
10aa0 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
10ab0 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66  in the middle of
10ac0 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63   a large transac
10ad0 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74  tion where all t
10ae0 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69  he.** changes wi
10af0 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20  ll not fit into 
10b00 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61  the in-memory ca
10b10 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  che.  SQLite wil
10b20 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c  l.** already hol
10b30 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63  d a RESERVED loc
10b40 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  k on the databas
10b50 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e  e file, but it n
10b60 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  eeds.** to promo
10b70 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20  te this lock to 
10b80 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61  EXCLUSIVE so tha
10b90 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63  t it can spill c
10ba0 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e  ache.** pages in
10bb0 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
10bc0 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72  file without har
10bd0 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a  m to concurrent.
10be0 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 20  ** readers.  If 
10bf0 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
10c00 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b  promote the lock
10c10 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65  , then the in-me
10c20 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69  mory.** cache wi
10c30 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e  ll be left in an
10c40 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74   inconsistent st
10c50 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65  ate and so the e
10c60 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20  rror.** code is 
10c70 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68  promoted from th
10c80 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e  e relatively ben
10c90 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  ign [SQLITE_BUSY
10ca0 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ] to.** the more
10cb0 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f   severe [SQLITE_
10cc0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20  IOERR_BLOCKED]. 
10cd0 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65   This error code
10ce0 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f   promotion.** fo
10cf0 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69  rces an automati
10d00 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68  c rollback of th
10d10 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20  e changes.  See 
10d20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
10d30 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d  /cvstrac/wiki?p=
10d40 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
10d50 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a  ingBusyError">.*
10d60 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  * CorruptionFoll
10d70 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f  owingBusyError</
10d80 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72  a> wiki page for
10d90 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66   a discussion of
10da0 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20   why.** this is 
10db0 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a  important..**.**
10dc0 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20   There can only 
10dd0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
10de0 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
10df0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
10e00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10e10 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
10e20 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
10e30 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
10e40 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
10e50 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74  dler.  Note that
10e60 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
10e70 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
10e80 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73  ].** will also s
10e90 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20  et or clear the 
10ea0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
10eb0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
10ec0 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 31 7d 20 54  **.** {H12311} T
10ed0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  he [sqlite3_busy
10ee0 5f 68 61 6e 64 6c 65 72 28 44 2c 43 2c 41 29 5d  _handler(D,C,A)]
10ef0 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
10f00 72 65 70 6c 61 63 65 0a 2a 2a 20 20 20 20 20 20  replace.**      
10f10 20 20 20 20 62 75 73 79 20 63 61 6c 6c 62 61 63      busy callbac
10f20 6b 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61  k in the [databa
10f30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
10f40 20 77 69 74 68 20 61 20 6e 65 77 0a 2a 2a 20 20   with a new.**  
10f50 20 20 20 20 20 20 20 20 61 20 6e 65 77 20 62 75          a new bu
10f60 73 79 20 68 61 6e 64 6c 65 72 20 43 20 61 6e 64  sy handler C and
10f70 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
10f80 61 20 70 6f 69 6e 74 65 72 20 41 2e 0a 2a 2a 0a  a pointer A..**.
10f90 2a 2a 20 7b 48 31 32 33 31 32 7d 20 4e 65 77 6c  ** {H12312} Newl
10fa0 79 20 63 72 65 61 74 65 64 20 5b 64 61 74 61 62  y created [datab
10fb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
10fc0 20 73 68 61 6c 6c 20 68 61 76 65 20 61 20 62 75   shall have a bu
10fd0 73 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  sy.**          h
10fe0 61 6e 64 6c 65 72 20 6f 66 20 4e 55 4c 4c 2e 0a  andler of NULL..
10ff0 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 34 7d 20 57  **.** {H12314} W
11000 68 65 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20  hen two or more 
11010 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11020 74 69 6f 6e 73 5d 20 73 68 61 72 65 20 61 0a 2a  tions] share a.*
11030 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
11040 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
11050 64 5f 63 61 63 68 65 20 7c 20 63 6f 6d 6d 6f 6e  d_cache | common
11060 20 63 61 63 68 65 5d 2c 0a 2a 2a 20 20 20 20 20   cache],.**     
11070 20 20 20 20 20 74 68 65 20 62 75 73 79 20 68 61       the busy ha
11080 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 64 61  ndler for the da
11090 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
110a0 6e 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  n currently usin
110b0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  g.**          th
110c0 65 20 63 61 63 68 65 20 73 68 61 6c 6c 20 62 65  e cache shall be
110d0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
110e0 65 20 63 61 63 68 65 20 65 6e 63 6f 75 6e 74 65  e cache encounte
110f0 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a  rs a lock..**.**
11100 20 7b 48 31 32 33 31 36 7d 20 49 66 20 61 20 62   {H12316} If a b
11110 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
11120 62 61 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 72  back returns zer
11130 6f 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 69  o, then the SQLi
11140 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  te interface.** 
11150 20 20 20 20 20 20 20 20 20 74 68 61 74 20 70 72           that pr
11160 6f 76 6f 6b 65 64 20 74 68 65 20 6c 6f 63 6b 69  ovoked the locki
11170 6e 67 20 65 76 65 6e 74 20 73 68 61 6c 6c 20 72  ng event shall r
11180 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
11190 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  SY]..**.** {H123
111a0 31 38 7d 20 53 51 4c 69 74 65 20 73 68 61 6c 6c  18} SQLite shall
111b0 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 62 75 73   invokes the bus
111c0 79 20 68 61 6e 64 6c 65 72 20 77 69 74 68 20 74  y handler with t
111d0 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 77 68 69  wo arguments whi
111e0 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ch.**          a
111f0 72 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  re a copy of the
11200 20 70 6f 69 6e 74 65 72 20 73 75 70 70 6c 69 65   pointer supplie
11210 64 20 62 79 20 74 68 65 20 33 72 64 20 70 61 72  d by the 3rd par
11220 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20  ameter to.**    
11230 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
11240 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 61  usy_handler()] a
11250 6e 64 20 61 20 63 6f 75 6e 74 20 6f 66 20 74 68  nd a count of th
11260 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 72 69 6f  e number of prio
11270 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  r.**          in
11280 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
11290 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
112a0 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69  r the same locki
112b0 6e 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  ng event..**.** 
112c0 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
112d0 2a 2a 20 7b 41 31 32 33 31 39 7d 20 41 20 62 75  ** {A12319} A bu
112e0 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
112f0 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
11300 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11310 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
11320 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11330 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
11340 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
11350 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
11360 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
11370 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
11380 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
11390 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
113a0 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
113b0 79 20 54 69 6d 65 6f 75 74 20 7b 48 31 32 33 34  y Timeout {H1234
113c0 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a  0} <S40410>.**.*
113d0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73  * This routine s
113e0 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
113f0 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
11400 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
11410 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
11420 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
11430 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
11440 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
11450 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a  .  The handler.*
11460 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  * will sleep mul
11470 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
11480 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  l at least "ms" 
11490 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
114a0 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65  sleeping.** have
114b0 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b 48   accumulated. {H
114c0 31 32 33 34 33 7d 20 41 66 74 65 72 20 22 6d 73  12343} After "ms
114d0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
114e0 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
114f0 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
11500 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
11510 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
11520 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
11530 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
11540 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
11550 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43  LOCKED]..**.** C
11560 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
11570 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
11580 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
11590 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
115a0 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
115b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
115c0 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20  **.** There can 
115d0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
115e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
115f0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
11600 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
11610 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20  ection] any any 
11620 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
11630 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
11640 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
11650 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
11660 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
11670 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
11680 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
11690 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
116a0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
116b0 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a  r is cleared..**
116c0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
116d0 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 31 7d 20 54  **.** {H12341} T
116e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  he [sqlite3_busy
116f0 5f 74 69 6d 65 6f 75 74 28 29 5d 20 66 75 6e 63  _timeout()] func
11700 74 69 6f 6e 20 73 68 61 6c 6c 20 6f 76 65 72 72  tion shall overr
11710 69 64 65 20 61 6e 79 20 70 72 69 6f 72 0a 2a 2a  ide any prior.**
11720 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
11730 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
11740 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62  )] or [sqlite3_b
11750 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 73  usy_handler()] s
11760 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  etting.**       
11770 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b     on the same [
11780 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11790 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ion]..**.** {H12
117a0 33 34 33 7d 20 49 66 20 74 68 65 20 32 6e 64 20  343} If the 2nd 
117b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
117c0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
117d0 75 74 28 29 5d 20 69 73 20 6c 65 73 73 20 74 68  ut()] is less th
117e0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  an.**          o
117f0 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2c  r equal to zero,
11800 20 74 68 65 6e 20 74 68 65 20 62 75 73 79 20 68   then the busy h
11810 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20 62 65 20  andler shall be 
11820 63 6c 65 61 72 65 64 20 73 6f 20 74 68 61 74 0a  cleared so that.
11830 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 20  **          all 
11840 73 75 62 73 65 71 75 65 6e 74 20 6c 6f 63 6b 69  subsequent locki
11850 6e 67 20 65 76 65 6e 74 73 20 69 6d 6d 65 64 69  ng events immedi
11860 61 74 65 6c 79 20 72 65 74 75 72 6e 20 5b 53 51  ately return [SQ
11870 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
11880 2a 20 7b 48 31 32 33 34 34 7d 20 49 66 20 74 68  * {H12344} If th
11890 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
118a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  to [sqlite3_busy
118b0 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 61  _timeout()] is a
118c0 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 20   positive.**    
118d0 20 20 20 20 20 20 6e 75 6d 62 65 72 20 4e 2c 20        number N, 
118e0 74 68 65 6e 20 61 20 62 75 73 79 20 68 61 6e 64  then a busy hand
118f0 6c 65 72 20 73 68 61 6c 6c 20 62 65 20 73 65 74  ler shall be set
11900 20 74 68 61 74 20 72 65 70 65 61 74 65 64 6c 79   that repeatedly
11910 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20   calls.**       
11920 20 20 20 74 68 65 20 78 53 6c 65 65 70 28 29 20     the xSleep() 
11930 6d 65 74 68 6f 64 20 69 6e 20 74 68 65 20 5b 73  method in the [s
11940 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53  qlite3_vfs | VFS
11950 20 69 6e 74 65 72 66 61 63 65 5d 20 75 6e 74 69   interface] unti
11960 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 69  l.**          ei
11970 74 68 65 72 20 74 68 65 20 6c 6f 63 6b 20 63 6c  ther the lock cl
11980 65 61 72 73 20 6f 72 20 75 6e 74 69 6c 20 74 68  ears or until th
11990 65 20 63 75 6d 75 6c 61 74 69 76 65 20 73 6c 65  e cumulative sle
119a0 65 70 20 74 69 6d 65 0a 2a 2a 20 20 20 20 20 20  ep time.**      
119b0 20 20 20 20 72 65 70 6f 72 74 65 64 20 62 61 63      reported bac
119c0 6b 20 62 79 20 78 53 6c 65 65 70 28 29 20 65 78  k by xSleep() ex
119d0 63 65 65 64 73 20 4e 20 6d 69 6c 6c 69 73 65 63  ceeds N millisec
119e0 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  onds..*/.int sql
119f0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
11a00 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
11a10 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
11a20 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
11a30 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
11a40 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 20 7b  unning Queries {
11a50 48 31 32 33 37 30 7d 20 3c 53 31 30 30 30 30 3e  H12370} <S10000>
11a60 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
11a70 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
11a80 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
11a90 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
11aa0 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
11ab0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
11ac0 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
11ad0 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
11ae0 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
11af0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
11b00 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
11b10 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
11b20 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
11b30 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
11b40 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
11b50 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
11b60 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
11b70 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
11b80 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
11b90 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
11ba0 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
11bb0 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
11bc0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
11bd0 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
11be0 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
11bf0 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
11c00 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
11c10 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
11c20 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
11c30 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
11c40 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
11c50 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
11c60 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
11c70 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
11c80 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
11c90 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
11ca0 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
11cb0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
11cc0 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
11cd0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
11ce0 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
11cf0 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
11d00 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
11d10 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
11d20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
11d30 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
11d40 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
11d50 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
11d60 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
11d70 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
11d80 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
11d90 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
11da0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
11db0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
11dc0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
11dd0 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
11de0 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
11df0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11e00 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
11e10 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
11e20 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
11e30 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
11e40 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
11e50 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
11e60 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
11e70 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
11e80 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
11e90 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78  ..**.** As an ex
11ea0 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73  ample of the res
11eb0 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74  ult table format
11ec0 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72  , suppose a quer
11ed0 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61  y result.** is a
11ee0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
11ef0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
11f00 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d  e>.**        Nam
11f10 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a  e        | Age.*
11f20 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d  *        -------
11f30 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
11f40 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65  .**        Alice
11f50 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20         | 43.**  
11f60 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20        Bob       
11f70 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20    | 28.**       
11f80 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32   Cindy       | 2
11f90 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  1.** </pre></blo
11fa0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
11fb0 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c  here are two col
11fc0 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74  umn (M==2) and t
11fd0 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29  hree rows (N==3)
11fe0 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72  .  Thus the.** r
11ff0 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20  esult table has 
12000 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70  8 entries.  Supp
12010 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74  ose the result t
12020 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a  able is stored.*
12030 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61  * in an array na
12040 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54  mes azResult.  T
12050 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c  hen azResult hol
12060 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a  ds this content:
12070 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
12080 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
12090 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
120a0 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20  0] = "Name";.** 
120b0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
120c0 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  #91;1] = "Age";.
120d0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
120e0 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69  lt&#91;2] = "Ali
120f0 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ce";.**        a
12100 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d  zResult&#91;3] =
12110 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "43";.**       
12120 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d   azResult&#91;4]
12130 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20   = "Bob";.**    
12140 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
12150 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  ;5] = "28";.**  
12160 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
12170 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b  91;6] = "Cindy";
12180 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
12190 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31  ult&#91;7] = "21
121a0 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
121b0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
121c0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
121d0 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
121e0 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
121f0 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
12200 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
12210 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
12220 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
12230 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
12240 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
12250 61 72 61 6d 65 74 65 72 2e 20 20 49 74 20 72 65  arameter.  It re
12260 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
12270 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
12280 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
12290 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
122a0 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
122b0 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
122c0 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
122d0 20 75 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c   using the resul
122e0 74 2c 20 69 74 20 73 68 6f 75 6c 64 0a 2a 2a 20  t, it should.** 
122f0 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
12300 20 74 6f 20 74 68 65 20 72 65 73 75 6c 74 20 74   to the result t
12310 61 62 6c 65 20 74 6f 20 73 71 6c 69 74 65 33 5f  able to sqlite3_
12320 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
12330 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
12340 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
12350 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
12360 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
12370 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
12380 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
12390 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
123a0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
123b0 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
123c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
123d0 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
123e0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
123f0 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
12400 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
12410 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
12420 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
12430 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
12440 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
12450 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
12460 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
12470 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
12480 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
12490 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
124a0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
124b0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
124c0 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
124d0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
124e0 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
124f0 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
12500 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
12510 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
12520 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
12530 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
12540 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
12550 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
12560 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
12570 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
12580 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
12590 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
125a0 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
125b0 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
125c0 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
125d0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
125e0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
125f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
12600 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  rmsg()]..**.** I
12610 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
12620 20 7b 48 31 32 33 37 31 7d 20 49 66 20 61 20 5b   {H12371} If a [
12630 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
12640 65 28 29 5d 20 66 61 69 6c 73 20 61 20 6d 65 6d  e()] fails a mem
12650 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ory allocation, 
12660 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
12670 20 69 74 20 73 68 61 6c 6c 20 66 72 65 65 20 74   it shall free t
12680 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
12690 75 6e 64 65 72 20 63 6f 6e 73 74 72 75 63 74 69  under constructi
126a0 6f 6e 2c 20 61 62 6f 72 74 20 74 68 65 0a 2a 2a  on, abort the.**
126b0 20 20 20 20 20 20 20 20 20 20 71 75 65 72 79 20            query 
126c0 69 6e 20 70 72 6f 63 65 73 73 2c 20 73 6b 69 70  in process, skip
126d0 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
126e0 71 75 65 72 69 65 73 2c 20 73 65 74 20 74 68 65  queries, set the
126f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 70 61  .**          *pa
12700 7a 52 65 73 75 6c 74 20 6f 75 74 70 75 74 20 70  zResult output p
12710 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 61  ointer to NULL a
12720 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
12730 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
12740 7b 48 31 32 33 37 33 7d 20 49 66 20 74 68 65 20  {H12373} If the 
12750 70 6e 43 6f 6c 75 6d 6e 20 70 61 72 61 6d 65 74  pnColumn paramet
12760 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67  er to [sqlite3_g
12770 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e  et_table()] is n
12780 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20  ot NULL.**      
12790 20 20 20 20 74 68 65 6e 20 61 20 73 75 63 63 65      then a succe
127a0 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
127b0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   of [sqlite3_get
127c0 5f 74 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a  _table()] shall.
127d0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 72 69 74  **          writ
127e0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
127f0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a  columns in the.*
12800 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c  *          resul
12810 74 20 73 65 74 20 6f 66 20 74 68 65 20 71 75 65  t set of the que
12820 72 79 20 69 6e 74 6f 20 2a 70 6e 43 6f 6c 75 6d  ry into *pnColum
12830 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 34  n..**.** {H12374
12840 7d 20 49 66 20 74 68 65 20 70 6e 52 6f 77 20 70  } If the pnRow p
12850 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
12860 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
12870 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a  ] is not NULL.**
12880 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 61            then a
12890 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
128a0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
128b0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
128c0 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  shall.**        
128d0 20 20 77 72 69 74 65 73 20 74 68 65 20 6e 75 6d    writes the num
128e0 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 20 74  ber of rows in t
128f0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
12900 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65  esult set of the
12910 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 70 6e 52   query into *pnR
12920 6f 77 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37  ow..**.** {H1237
12930 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  6} A successful 
12940 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
12950 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
12960 28 29 5d 20 74 68 61 74 20 63 6f 6d 70 75 74 65  ()] that compute
12970 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 20  s.**          N 
12980 72 6f 77 73 20 6f 66 20 72 65 73 75 6c 74 20 77  rows of result w
12990 69 74 68 20 43 20 63 6f 6c 75 6d 6e 73 20 70 65  ith C columns pe
129a0 72 20 72 6f 77 20 73 68 61 6c 6c 20 6d 61 6b 65  r row shall make
129b0 20 2a 70 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 20   *pazResult.**  
129c0 20 20 20 20 20 20 20 20 70 6f 69 6e 74 20 74 6f          point to
129d0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
129e0 6e 74 65 72 73 20 74 6f 20 28 4e 2b 31 29 2a 43  nters to (N+1)*C
129f0 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 74   strings where t
12a00 68 65 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20  he first.**     
12a10 20 20 20 20 20 43 20 73 74 72 69 6e 67 73 20 61       C strings a
12a20 72 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20  re column names 
12a30 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  as obtained from
12a40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
12a50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
12a60 65 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73  e()] and the res
12a70 74 20 61 72 65 20 63 6f 6c 75 6d 6e 20 72 65 73  t are column res
12a80 75 6c 74 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20  ult values.**   
12a90 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20         obtained 
12aa0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
12ab0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
12ac0 0a 2a 2a 20 7b 48 31 32 33 37 39 7d 20 54 68 65  .** {H12379} The
12ad0 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 70   values in the p
12ae0 61 7a 52 65 73 75 6c 74 20 61 72 72 61 79 20 72  azResult array r
12af0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
12b00 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
12b10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61  .**          sha
12b20 6c 6c 20 72 65 6d 61 69 6e 20 76 61 6c 69 64 20  ll remain valid 
12b30 75 6e 74 69 6c 20 63 6c 65 61 72 65 64 20 62 79  until cleared by
12b40 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
12b50 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  able()]..**.** {
12b60 48 31 32 33 38 32 7d 20 57 68 65 6e 20 61 6e 20  H12382} When an 
12b70 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
12b80 69 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ing evaluation o
12b90 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  f [sqlite3_get_t
12ba0 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20  able()].**      
12bb0 20 20 20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e      the function
12bc0 20 73 68 61 6c 6c 20 73 65 74 20 2a 70 61 7a 52   shall set *pazR
12bd0 65 73 75 6c 74 20 74 6f 20 4e 55 4c 4c 2c 20 77  esult to NULL, w
12be0 72 69 74 65 20 61 6e 20 65 72 72 6f 72 20 6d 65  rite an error me
12bf0 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  ssage.**        
12c00 20 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62    into memory ob
12c10 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
12c20 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
12c30 6d 61 6b 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  make.**         
12c40 20 2a 2a 70 7a 45 72 72 6d 73 67 20 70 6f 69 6e   **pzErrmsg poin
12c50 74 20 74 6f 20 74 68 61 74 20 65 72 72 6f 72 20  t to that error 
12c60 6d 65 73 73 61 67 65 2c 20 61 6e 64 20 72 65 74  message, and ret
12c70 75 72 6e 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  urn a.**        
12c80 20 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65    appropriate [e
12c90 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69  rror code]..*/.i
12ca0 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
12cb0 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
12cc0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
12cd0 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
12ce0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
12cf0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
12d00 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
12d10 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
12d20 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
12d30 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
12d40 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
12d50 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
12d60 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
12d70 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
12d80 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
12d90 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
12da0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
12db0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
12dc0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
12dd0 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
12de0 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
12df0 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
12e00 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
12e10 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
12e20 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
12e30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12e40 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
12e50 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
12e60 6f 6e 73 20 7b 48 31 37 34 30 30 7d 20 3c 53 37  ons {H17400} <S7
12e70 30 30 30 30 3e 3c 53 32 30 30 30 30 3e 0a 2a 2a  0000><S20000>.**
12e80 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
12e90 65 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65  es are workalike
12ea0 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
12eb0 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
12ec0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
12ed0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
12ee0 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  ibrary..**.** Th
12ef0 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
12f00 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
12f10 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
12f20 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
12f30 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
12f40 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
12f50 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
12f60 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
12f70 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
12f80 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
12f90 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
12fa0 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
12fb0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
12fc0 2e 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73  .  Both routines
12fd0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
12fe0 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
12ff0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
13000 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
13010 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
13020 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
13030 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
13040 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71  ing..**.** In sq
13050 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
13060 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
13070 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
13080 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
13090 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
130a0 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
130b0 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
130c0 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
130d0 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
130e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
130f0 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
13100 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
13110 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
13120 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
13130 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
13140 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
13150 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
13160 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54  m snprintf().  T
13170 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
13180 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
13190 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
131a0 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
131b0 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
131c0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
131d0 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68  y.  Note also th
131e0 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
131f0 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
13200 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
13210 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
13220 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
13230 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
13240 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
13250 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
13260 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  .  We admit that
13270 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
13280 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
13290 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
132a0 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
132b0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
132c0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
132d0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
132e0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
132f0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
13300 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
13310 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
13320 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61  .**.** As long a
13330 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
13340 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
13350 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
13360 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
13370 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
13380 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
13390 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
133a0 65 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ed.  The first.*
133b0 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
133c0 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
133d0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
133e0 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
133f0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
13400 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
13410 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
13420 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
13430 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
13440 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
13450 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
13460 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
13470 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
13480 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
13490 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
134a0 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
134b0 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
134c0 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
134d0 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
134e0 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
134f0 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
13500 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
13510 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
13520 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
13530 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a  ", "%Q", and "%z
13540 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
13550 20 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77   The %q option w
13560 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
13570 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
13580 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69  tes a null-termi
13590 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
135a0 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
135b0 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
135c0 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
135d0 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
135e0 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
135f0 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
13600 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
13610 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69  eral.  By doubli
13620 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
13630 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
13640 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
13650 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
13660 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
13670 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
13680 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
13690 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74  xample, assume t
136a0 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  he string variab
136b0 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e  le zText contain
136c0 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77  s text as follow
136d0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
136e0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
136f0 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74  har *zText = "It
13700 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22  's a happy day!"
13710 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
13720 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f  ckquote>.**.** O
13730 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
13740 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
13750 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
13760 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
13770 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
13780 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
13790 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
137a0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
137b0 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20   VALUES('%q')", 
137c0 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
137d0 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
137e0 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
137f0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
13800 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
13810 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
13820 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71  * Because the %q
13830 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
13840 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27  s used, the '\''
13850 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54   character in zT
13860 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65  ext.** is escape
13870 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65  d and the SQL ge
13880 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f  nerated is as fo
13890 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
138a0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
138b0 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
138c0 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
138d0 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  ''s a happy day!
138e0 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ').** </pre></bl
138f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
13900 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e  This is correct.
13910 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73    Had we used %s
13920 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20   instead of %q, 
13930 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51  the generated SQ
13940 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20  L.** would have 
13950 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73  looked like this
13960 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
13970 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
13980 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
13990 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20   VALUES('It's a 
139a0 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a  happy day!');.**
139b0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
139c0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
139d0 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69  second example i
139e0 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20  s an SQL syntax 
139f0 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e  error.  As a gen
13a00 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68  eral rule you sh
13a10 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75  ould.** always u
13a20 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66  se %q instead of
13a30 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69   %s when inserti
13a40 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73  ng text into a s
13a50 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a  tring literal..*
13a60 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69  *.** The %Q opti
13a70 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
13a80 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
13a90 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
13aa0 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
13ab0 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
13ac0 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
13ad0 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
13ae0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
13af0 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
13b00 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
13b10 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
13b20 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
13b30 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
13b40 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
13b50 73 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  s) in place of t
13b60 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53  he %Q option.  S
13b70 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
13b80 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
13b90 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
13ba0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
13bb0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
13bc0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
13bd0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
13be0 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
13bf0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
13c00 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
13c10 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
13c20 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
13c30 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
13c40 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
13c50 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
13c60 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
13c70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
13c80 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
13c90 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
13ca0 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
13cb0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
13cc0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a  r..**.** The "%z
13cd0 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
13ce0 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c  ion works exactl
13cf0 79 20 6c 69 6b 65 20 22 25 73 22 20 77 69 74 68  y like "%s" with
13d00 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
13d10 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
13d20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
13d30 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
13d40 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
13d50 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
13d60 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
13d70 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
13d80 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ng. {END}.**.** 
13d90 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
13da0 2a 20 7b 48 31 37 34 30 33 7d 20 20 54 68 65 20  * {H17403}  The 
13db0 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
13dc0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
13dd0 5f 76 6d 70 72 69 6e 74 66 28 29 5d 20 69 6e 74  _vmprintf()] int
13de0 65 72 66 61 63 65 73 0a 2a 2a 20 20 20 20 20 20  erfaces.**      
13df0 20 20 20 20 20 72 65 74 75 72 6e 20 65 69 74 68       return eith
13e00 65 72 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  er pointers to z
13e10 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
13e20 54 46 2d 38 20 73 74 72 69 6e 67 73 20 68 65 6c  TF-8 strings hel
13e30 64 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  d in.**         
13e40 20 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65    memory obtaine
13e50 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
13e60 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 4e 55 4c  malloc()] or NUL
13e70 4c 20 70 6f 69 6e 74 65 72 73 20 69 66 0a 2a 2a  L pointers if.**
13e80 20 20 20 20 20 20 20 20 20 20 20 61 20 63 61 6c             a cal
13e90 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  l to [sqlite3_ma
13ea0 6c 6c 6f 63 28 29 5d 20 66 61 69 6c 73 2e 0a 2a  lloc()] fails..*
13eb0 2a 0a 2a 2a 20 7b 48 31 37 34 30 36 7d 20 20 54  *.** {H17406}  T
13ec0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  he [sqlite3_snpr
13ed0 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63  intf()] interfac
13ee0 65 20 77 72 69 74 65 73 20 61 20 7a 65 72 6f 2d  e writes a zero-
13ef0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20  terminated.**   
13f00 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74          UTF-8 st
13f10 72 69 6e 67 20 69 6e 74 6f 20 74 68 65 20 62 75  ring into the bu
13f20 66 66 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20  ffer pointed to 
13f30 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
13f40 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20  rameter.**      
13f50 20 20 20 20 20 70 72 6f 76 69 64 65 64 20 74 68       provided th
13f60 61 74 20 74 68 65 20 66 69 72 73 74 20 70 61 72  at the first par
13f70 61 6d 65 74 65 72 20 69 73 20 67 72 65 61 74 65  ameter is greate
13f80 72 20 74 68 61 6e 20 7a 65 72 6f 2e 0a 2a 2a 0a  r than zero..**.
13f90 2a 2a 20 7b 48 31 37 34 30 37 7d 20 20 54 68 65  ** {H17407}  The
13fa0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
13fb0 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  tf()] interface 
13fc0 64 6f 65 73 20 6e 6f 74 20 77 72 69 74 65 20 73  does not write s
13fd0 6c 6f 74 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20  lots of.**      
13fe0 20 20 20 20 20 69 74 73 20 6f 75 74 70 75 74 20       its output 
13ff0 62 75 66 66 65 72 20 28 74 68 65 20 73 65 63 6f  buffer (the seco
14000 6e 64 20 70 61 72 61 6d 65 74 65 72 29 20 6f 75  nd parameter) ou
14010 74 73 69 64 65 20 74 68 65 20 72 61 6e 67 65 0a  tside the range.
14020 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 66 20  **           of 
14030 30 20 74 68 72 6f 75 67 68 20 4e 2d 31 20 28 77  0 through N-1 (w
14040 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 66 69  here N is the fi
14050 72 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  rst parameter).*
14060 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 67 61  *           rega
14070 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6c 65  rdless of the le
14080 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
14090 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ng.**           
140a0 72 65 71 75 65 73 74 65 64 20 62 79 20 74 68 65  requested by the
140b0 20 66 6f 72 6d 61 74 20 73 70 65 63 69 66 69 63   format specific
140c0 61 74 69 6f 6e 2e 0a 2a 2f 0a 63 68 61 72 20 2a  ation..*/.char *
140d0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
140e0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
140f0 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
14100 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
14110 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
14120 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
14130 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
14140 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
14150 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
14160 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
14170 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d  cation Subsystem
14180 20 7b 48 31 37 33 30 30 7d 20 3c 53 32 30 30 30   {H17300} <S2000
14190 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  0>.**.** The SQL
141a0 69 74 65 20 63 6f 72 65 20 20 75 73 65 73 20 74  ite core  uses t
141b0 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
141c0 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
141d0 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
141e0 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
141f0 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
14200 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
14210 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
14220 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
14230 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
14240 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
14250 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
14260 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
14270 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
14280 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
14290 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
142a0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
142b0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
142c0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
142d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
142e0 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
142f0 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
14300 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
14310 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
14320 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20  arameter..** If 
14330 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14340 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
14350 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
14360 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
14370 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
14380 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 74  L pointer.  If t
14390 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74  he parameter N t
143a0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  o.** sqlite3_mal
143b0 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
143c0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73   negative then s
143d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
143e0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c  returns.** a NUL
143f0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
14400 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   Calling sqlite3
14410 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
14420 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
14430 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
14440 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
14450 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
14460 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
14470 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
14480 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
14490 62 65 20 72 65 75 73 65 64 2e 20 20 54 68 65 20  be reused.  The 
144a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72  sqlite3_free() r
144b0 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e  outine is.** a n
144c0 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65  o-op if is calle
144d0 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
144e0 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20  inter.  Passing 
144f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
14500 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  * to sqlite3_fre
14510 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  e() is harmless.
14520 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72    After being fr
14530 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73  eed, memory.** s
14540 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65  hould neither be
14550 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65   read nor writte
14560 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67  n.  Even reading
14570 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65   previously free
14580 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68  d.** memory migh
14590 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65  t result in a se
145a0 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
145b0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
145c0 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72   error..** Memor
145d0 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20  y corruption, a 
145e0 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
145f0 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76  lt, or other sev
14600 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67  ere error.** mig
14610 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c  ht result if sql
14620 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63  ite3_free() is c
14630 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e  alled with a non
14640 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68  -NULL pointer th
14650 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62  at.** was not ob
14660 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
14670 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
14680 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 2e 0a  sqlite3_free()..
14690 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
146a0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65  3_realloc() inte
146b0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
146c0 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
146d0 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
146e0 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c  ation to be at l
146f0 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68  east N bytes, wh
14700 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
14710 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
14720 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c  .  The memory al
14730 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72  location to be r
14740 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69  esized is the fi
14750 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
14760 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20  .  If the first 
14770 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
14780 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
14790 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
147a0 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
147b0 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
147c0 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
147d0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
147e0 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  N) where N is th
147f0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
14800 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
14810 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74  alloc()..** If t
14820 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
14830 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
14840 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  ealloc() is zero
14850 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
14860 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
14870 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
14880 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
14890 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
148a0 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74  (P) where P is t
148b0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
148c0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
148d0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69  alloc()..** sqli
148e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
148f0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
14900 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  to a memory allo
14910 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20  cation.** of at 
14920 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
14930 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66   size or NULL if
14940 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f   sufficient memo
14950 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  ry is unavailabl
14960 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68  e..** If M is th
14970 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
14980 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
14990 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
149a0 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
149b0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
149c0 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
149d0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
149e0 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
149f0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
14a00 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20  alloc() and the 
14a10 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
14a20 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66   is freed..** If
14a30 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
14a40 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c  () returns NULL,
14a50 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20   then the prior 
14a60 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73  allocation.** is
14a70 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
14a80 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74  * The memory ret
14a90 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
14aa0 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71  _malloc() and sq
14ab0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
14ac0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
14ad0 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
14ae0 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
14af0 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ary. {END}.**.**
14b00 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70   The default imp
14b10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
14b20 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
14b30 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75  tion subsystem u
14b40 73 65 73 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f  ses.** the mallo
14b50 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61  c(), realloc() a
14b60 6e 64 20 66 72 65 65 28 29 20 70 72 6f 76 69 64  nd free() provid
14b70 65 64 20 62 79 20 74 68 65 20 73 74 61 6e 64 61  ed by the standa
14b80 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
14b90 20 7b 48 31 37 33 38 32 7d 20 48 6f 77 65 76 65   {H17382} Howeve
14ba0 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
14bb0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
14bc0 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f  e.** SQLITE_MEMO
14bd0 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f  RY_SIZE=<i>NNN</
14be0 69 3e 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  i> C preprocesso
14bf0 72 20 6d 61 63 72 6f 20 28 77 68 65 72 65 20 3c  r macro (where <
14c00 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20  i>NNN</i>.** is 
14c10 61 6e 20 69 6e 74 65 67 65 72 29 2c 20 74 68 65  an integer), the
14c20 6e 20 53 51 4c 69 74 65 20 63 72 65 61 74 65 20  n SQLite create 
14c30 61 20 73 74 61 74 69 63 20 61 72 72 61 79 20 6f  a static array o
14c40 66 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69  f at least.** <i
14c50 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69  >NNN</i> bytes i
14c60 6e 20 73 69 7a 65 20 61 6e 64 20 75 73 65 73 20  n size and uses 
14c70 74 68 61 74 20 61 72 72 61 79 20 66 6f 72 20 61  that array for a
14c80 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
14c90 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  c.** memory allo
14ca0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45  cation needs. {E
14cb0 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  ND}  Additional 
14cc0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
14cd0 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20   options.** may 
14ce0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
14cf0 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a  re releases..**.
14d00 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
14d10 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
14d20 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
14d30 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
14d40 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
14d50 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
14d60 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
14d70 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
14d80 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
14d90 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
14da0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
14db0 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
14dc0 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
14dd0 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
14de0 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
14df0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
14e00 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
14e10 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77  **.** The Window
14e20 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
14e30 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68  ayer calls.** th
14e40 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
14e50 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
14e60 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
14e70 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
14e80 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
14e90 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
14ea0 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
14eb0 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
14ec0 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
14ed0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
14ee0 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
14ef0 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
14f00 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
14f10 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20  tion errors are 
14f20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
14f30 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74   they are report
14f40 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
14f50 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
14f60 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
14f70 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
14f80 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
14f90 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
14fa0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 33 7d 20 20  **.** {H17303}  
14fb0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  The [sqlite3_mal
14fc0 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63  loc(N)] interfac
14fd0 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
14fe0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
14ff0 20 20 20 20 20 20 20 20 20 20 20 61 20 6e 65 77             a new
15000 6c 79 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 62  ly checked-out b
15010 6c 6f 63 6b 20 6f 66 20 61 74 20 6c 65 61 73 74  lock of at least
15020 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f   N bytes of memo
15030 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ry.**           
15040 74 68 61 74 20 69 73 20 38 2d 62 79 74 65 20 61  that is 8-byte a
15050 6c 69 67 6e 65 64 2c 20 6f 72 20 69 74 20 72 65  ligned, or it re
15060 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 74  turns NULL if it
15070 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20 20 20   is unable.**   
15080 20 20 20 20 20 20 20 20 74 6f 20 66 75 6c 66 69          to fulfi
15090 6c 6c 20 74 68 65 20 72 65 71 75 65 73 74 2e 0a  ll the request..
150a0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 34 7d 20 20  **.** {H17304}  
150b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  The [sqlite3_mal
150c0 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63  loc(N)] interfac
150d0 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
150e0 20 70 6f 69 6e 74 65 72 20 69 66 0a 2a 2a 20 20   pointer if.**  
150f0 20 20 20 20 20 20 20 20 20 4e 20 69 73 20 6c 65           N is le
15100 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
15110 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20   to zero..**.** 
15120 7b 48 31 37 33 30 35 7d 20 20 54 68 65 20 5b 73  {H17305}  The [s
15130 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d 20  qlite3_free(P)] 
15140 69 6e 74 65 72 66 61 63 65 20 72 65 6c 65 61 73  interface releas
15150 65 73 20 6d 65 6d 6f 72 79 20 70 72 65 76 69 6f  es memory previo
15160 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  usly.**         
15170 20 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20    returned from 
15180 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
15190 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
151a0 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20  ealloc()],.**   
151b0 20 20 20 20 20 20 20 20 6d 61 6b 69 6e 67 20 69          making i
151c0 74 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20  t available for 
151d0 72 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  reuse..**.** {H1
151e0 37 33 30 36 7d 20 20 41 20 63 61 6c 6c 20 74 6f  7306}  A call to
151f0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 4e   [sqlite3_free(N
15200 55 4c 4c 29 5d 20 69 73 20 61 20 68 61 72 6d 6c  ULL)] is a harml
15210 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a  ess no-op..**.**
15220 20 7b 48 31 37 33 31 30 7d 20 20 41 20 63 61 6c   {H17310}  A cal
15230 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
15240 61 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69 73 20 65  alloc(0,N)] is e
15250 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63  quivalent to a c
15260 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
15270 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
15280 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  loc(N)]..**.** {
15290 48 31 37 33 31 32 7d 20 20 41 20 63 61 6c 6c 20  H17312}  A call 
152a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  to [sqlite3_real
152b0 6c 6f 63 28 50 2c 30 29 5d 20 69 73 20 65 71 75  loc(P,0)] is equ
152c0 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c  ivalent to a cal
152d0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  l.**           t
152e0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
152f0 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  P)]..**.** {H173
15300 31 35 7d 20 20 54 68 65 20 53 51 4c 69 74 65 20  15}  The SQLite 
15310 63 6f 72 65 20 75 73 65 73 20 5b 73 71 6c 69 74  core uses [sqlit
15320 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
15330 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
15340 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ],.**           
15350 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  and [sqlite3_fre
15360 65 28 29 5d 20 66 6f 72 20 61 6c 6c 20 6f 66 20  e()] for all of 
15370 69 74 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  its memory alloc
15380 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20  ation and.**    
15390 20 20 20 20 20 20 20 64 65 61 6c 6c 6f 63 61 74         deallocat
153a0 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ion needs..**.**
153b0 20 7b 48 31 37 33 31 38 7d 20 20 54 68 65 20 5b   {H17318}  The [
153c0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
153d0 50 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  P,N)] interface 
153e0 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 20 61  returns either a
153f0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20   pointer.**     
15400 20 20 20 20 20 20 74 6f 20 61 20 62 6c 6f 63 6b        to a block
15410 20 6f 66 20 63 68 65 63 6b 65 64 2d 6f 75 74 20   of checked-out 
15420 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61  memory of at lea
15430 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
15440 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ze.**           
15450 74 68 61 74 20 69 73 20 38 2d 62 79 74 65 20 61  that is 8-byte a
15460 6c 69 67 6e 65 64 2c 20 6f 72 20 61 20 4e 55 4c  ligned, or a NUL
15470 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
15480 20 7b 48 31 37 33 32 31 7d 20 20 57 68 65 6e 20   {H17321}  When 
15490 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
154a0 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61  (P,N)] returns a
154b0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
154c0 72 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20  r, it first.**  
154d0 20 20 20 20 20 20 20 20 20 63 6f 70 69 65 73 20           copies 
154e0 74 68 65 20 66 69 72 73 74 20 4b 20 62 79 74 65  the first K byte
154f0 73 20 6f 66 20 63 6f 6e 74 65 6e 74 20 66 72 6f  s of content fro
15500 6d 20 50 20 69 6e 74 6f 20 74 68 65 20 6e 65 77  m P into the new
15510 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ly.**           
15520 61 6c 6c 6f 63 61 74 65 64 20 62 6c 6f 63 6b 2c  allocated block,
15530 20 77 68 65 72 65 20 4b 20 69 73 20 74 68 65 20   where K is the 
15540 6c 65 73 73 65 72 20 6f 66 20 4e 20 61 6e 64 20  lesser of N and 
15550 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 20  the size of.**  
15560 20 20 20 20 20 20 20 20 20 74 68 65 20 62 75 66           the buf
15570 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  fer P..**.** {H1
15580 37 33 32 32 7d 20 20 57 68 65 6e 20 5b 73 71 6c  7322}  When [sql
15590 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e  ite3_realloc(P,N
155a0 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  )] returns a non
155b0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69  -NULL pointer, i
155c0 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20  t first.**      
155d0 20 20 20 20 20 72 65 6c 65 61 73 65 73 20 74 68       releases th
155e0 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a  e buffer P..**.*
155f0 2a 20 7b 48 31 37 33 32 33 7d 20 20 57 68 65 6e  * {H17323}  When
15600 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
15610 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20  c(P,N)] returns 
15620 4e 55 4c 4c 2c 20 74 68 65 20 62 75 66 66 65 72  NULL, the buffer
15630 20 50 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20   P is.**        
15640 20 20 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 20     not modified 
15650 6f 72 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  or released..**.
15660 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
15670 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 30 7d 20 20  **.** {A17350}  
15680 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
15690 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
156a0 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
156b0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
156c0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d  ].**           m
156d0 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55  ust be either NU
156e0 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74  LL or else point
156f0 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ers obtained fro
15700 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20  m a prior.**    
15710 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f         invocatio
15720 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
15730 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
15740 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
15750 68 61 74 20 68 61 76 65 0a 2a 2a 20 20 20 20 20  hat have.**     
15760 20 20 20 20 20 20 6e 6f 74 20 79 65 74 20 62 65        not yet be
15770 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
15780 2a 2a 20 7b 41 31 37 33 35 31 7d 20 20 54 68 65  ** {A17351}  The
15790 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
157a0 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
157b0 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
157c0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 62  **           a b
157d0 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61  lock of memory a
157e0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
157f0 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a   released using.
15800 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71  **           [sq
15810 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
15820 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
15830 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  c()]..*/.void *s
15840 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
15850 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
15860 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
15870 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
15880 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
15890 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
158a0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
158b0 6f 72 20 53 74 61 74 69 73 74 69 63 73 20 7b 48  or Statistics {H
158c0 31 37 33 37 30 7d 20 3c 53 33 30 32 31 30 3e 0a  17370} <S30210>.
158d0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
158e0 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
158f0 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
15900 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
15910 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
15920 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15930 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
15940 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
15950 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
15960 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
15970 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
15980 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
15990 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
159a0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
159b0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 31  S:.**.** {H17371
159c0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  } The [sqlite3_m
159d0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
159e0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
159f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
15a00 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  s.**          of
15a10 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c   memory currentl
15a20 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d  y outstanding (m
15a30 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20  alloced but not 
15a40 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48  freed)..**.** {H
15a50 31 37 33 37 33 7d 20 54 68 65 20 5b 73 71 6c 69  17373} The [sqli
15a60 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
15a70 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
15a80 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
15a90 6d 75 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  mum.**          
15aa0 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
15ab0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
15ac0 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
15ad0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20  water mark.**   
15ae0 20 20 20 20 20 20 20 77 61 73 20 6c 61 73 74 20         was last 
15af0 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  reset..**.** {H1
15b00 37 33 37 34 7d 20 54 68 65 20 76 61 6c 75 65 73  7374} The values
15b10 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
15b20 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
15b30 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20  d()] and.**     
15b40 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65       [sqlite3_me
15b50 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
15b60 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
15b70 65 72 68 65 61 64 0a 2a 2a 20 20 20 20 20 20 20  erhead.**       
15b80 20 20 20 61 64 64 65 64 20 62 79 20 53 51 4c 69     added by SQLi
15b90 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
15ba0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
15bb0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
15bc0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75 74 20  **          but 
15bd0 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
15be0 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
15bf0 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
15c00 6c 69 62 72 61 72 79 0a 2a 2a 20 20 20 20 20 20  library.**      
15c10 20 20 20 20 72 6f 75 74 69 6e 65 73 20 74 68 61      routines tha
15c20 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  t [sqlite3_mallo
15c30 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a  c()] may call..*
15c40 2a 0a 2a 2a 20 7b 48 31 37 33 37 35 7d 20 54 68  *.** {H17375} Th
15c50 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
15c60 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
15c70 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
15c80 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20   value of.**    
15c90 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d        [sqlite3_m
15ca0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66  emory_used()] if
15cb0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
15cc0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
15cd0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
15ce0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
15cf0 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
15d00 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   The value retur
15d10 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ned.**          
15d20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
15d30 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d  ry_highwater(1)]
15d40 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74   is the high-wat
15d50 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20  er mark.**      
15d60 20 20 20 20 70 72 69 6f 72 20 74 6f 20 74 68 65      prior to the
15d70 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
15d80 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
15d90 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
15da0 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
15db0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
15dc0 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
15dd0 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
15de0 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
15df0 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
15e00 20 47 65 6e 65 72 61 74 6f 72 20 7b 48 31 37 33   Generator {H173
15e10 39 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a  90} <S20000>.**.
15e20 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
15e30 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
15e40 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
15e50 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
15e60 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
15e70 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
15e80 20 52 4f 57 49 44 73 20 77 68 65 6e 20 69 6e 73   ROWIDs when ins
15e90 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
15ea0 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
15eb0 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
15ec0 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
15ed0 20 70 6f 73 73 69 62 6c 65 20 52 4f 57 49 44 2e   possible ROWID.
15ee0 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
15ef0 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
15f00 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
15f10 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
15f20 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
15f30 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
15f40 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
15f50 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
15f60 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
15f70 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
15f80 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  rposes..**.** A 
15f90 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
15fa0 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79  tine stores N by
15fb0 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
15fc0 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
15fd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
15fe0 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69   time this routi
15ff0 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65  ne is invoked (e
16000 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79  ither internally
16010 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70   or by.** the ap
16020 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50  plication) the P
16030 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73  RNG is seeded us
16040 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
16050 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
16060 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
16070 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
16080 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
16090 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f  fs] object..** O
160a0 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  n all subsequent
160b0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68   invocations, th
160c0 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
160d0 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
160e0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
160f0 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
16100 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
16110 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
16120 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
16130 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
16140 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 39 32 7d  :.**.** {H17392}
16150 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 61   The [sqlite3_ra
16160 6e 64 6f 6d 6e 65 73 73 28 4e 2c 50 29 5d 20 69  ndomness(N,P)] i
16170 6e 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20  nterface writes 
16180 4e 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20  N bytes of.**   
16190 20 20 20 20 20 20 20 68 69 67 68 2d 71 75 61 6c         high-qual
161a0 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
161b0 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
161c0 72 20 50 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  r P..*/.void sql
161d0 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
161e0 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
161f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16200 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
16210 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
16220 6c 62 61 63 6b 73 20 7b 48 31 32 35 30 30 7d 20  lbacks {H12500} 
16230 3c 53 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S70100>.**.** T
16240 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
16250 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a  sters a authoriz
16260 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
16270 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
16280 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
16290 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
162a0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
162b0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61  gument..** The a
162c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
162d0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
162e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
162f0 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
16300 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
16310 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
16320 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
16330 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
16340 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
16350 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
16360 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
16370 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20  re16_v2()].  At 
16380 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
16390 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
163a0 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
163b0 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
163c0 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
163d0 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
163e0 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
163f0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
16400 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
16410 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
16420 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
16430 6f 77 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f  owed.  The autho
16440 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
16450 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
16460 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
16470 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
16480 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
16490 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
164a0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
164b0 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
164c0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
164d0 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
164e0 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
164f0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
16500 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
16510 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
16520 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
16530 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
16540 72 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 6f  r.  If the autho
16550 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
16560 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
16570 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
16580 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
16590 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
165a0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
165b0 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
165c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
165d0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
165e0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
165f0 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
16600 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
16610 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
16620 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
16630 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
16640 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
16650 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
16660 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
16670 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
16680 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
16690 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
166a0 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
166b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
166c0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
166d0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
166e0 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a  triggered the.**
166f0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
16700 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
16710 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c  ror message expl
16720 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61  aining that.** a
16730 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
16740 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69    If the authori
16750 7a 65 72 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  zer code is [SQL
16760 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
16770 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
16780 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
16790 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
167a0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
167b0 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
167c0 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
167d0 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
167e0 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
167f0 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
16800 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
16810 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
16820 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
16830 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
16840 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
16850 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
16860 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
16870 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
16880 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
16890 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
168a0 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
168b0 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  f a table..**.**
168c0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
168d0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
168e0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
168f0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
16900 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
16910 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
16920 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
16930 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 54  r() interface. T
16940 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
16950 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
16960 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
16970 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
16980 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
16990 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
169a0 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
169b0 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
169c0 75 74 68 6f 72 69 7a 65 64 2e 20 54 68 65 20 74  uthorized. The t
169d0 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
169e0 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  th parameters.**
169f0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
16a00 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
16a10 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
16a20 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69  t contain additi
16a30 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20  onal.** details 
16a40 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
16a50 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
16a60 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  d..**.** An auth
16a70 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
16a80 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
16a90 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
16aa0 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
16ab0 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
16ac0 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
16ad0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
16ae0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
16af0 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
16b00 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
16b10 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
16b20 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
16b30 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
16b40 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
16b50 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
16b60 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
16b70 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
16b80 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
16b90 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
16ba0 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
16bb0 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
16bc0 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
16bd0 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
16be0 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
16bf0 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
16c00 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
16c10 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
16c20 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
16c30 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
16c40 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
16c50 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
16c60 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
16c70 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
16c80 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
16c90 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
16ca0 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
16cb0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
16cc0 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
16cd0 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
16ce0 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
16cf0 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
16d00 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
16d10 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
16d20 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
16d30 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
16d40 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
16d50 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
16d60 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
16d70 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
16d80 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
16d90 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
16da0 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
16db0 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
16dc0 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
16dd0 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
16de0 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
16df0 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20  r..**.** Only a 
16e00 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
16e10 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
16e20 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
16e30 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
16e40 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
16e50 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
16e60 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
16e70 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
16e80 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44  revious call.  D
16e90 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
16ea0 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
16eb0 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
16ec0 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
16ed0 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
16ee0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
16ef0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
16f00 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
16f10 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
16f20 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
16f30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
16f40 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
16f50 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
16f60 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
16f70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
16f80 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
16f90 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
16fa0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
16fb0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
16fc0 2a 20 7b 48 31 32 35 30 31 7d 20 54 68 65 20 5b  * {H12501} The [
16fd0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
16fe0 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e 29 5d 20 69  orizer(D,...)] i
16ff0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
17000 72 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  rs a.**         
17010 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17020 62 61 63 6b 20 77 69 74 68 20 64 61 74 61 62 61  back with databa
17030 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
17040 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 32 7d 20  .**.** {H12502} 
17050 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
17060 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
17070 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
17080 65 6e 74 73 20 61 72 65 0a 2a 2a 20 20 20 20 20  ents are.**     
17090 20 20 20 20 20 62 65 69 6e 67 20 63 6f 6d 70 69       being compi
170a0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  led..**.** {H125
170b0 30 33 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f  03} If the autho
170c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
170d0 65 74 75 72 6e 73 20 61 6e 79 20 76 61 6c 75 65  eturns any value
170e0 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20   other than.**  
170f0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
17100 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
17110 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
17120 5f 44 45 4e 59 5d 2c 20 74 68 65 6e 0a 2a 2a 20  _DENY], then.** 
17130 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
17140 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
17150 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
17160 74 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73  t call that caus
17170 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ed.**          t
17180 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
17190 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68  llback to run sh
171a0 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  all fail with an
171b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
171c0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f  LITE_ERROR] erro
171d0 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 61 70  r code and an ap
171e0 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20  propriate error 
171f0 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b  message..**.** {
17200 48 31 32 35 30 34 7d 20 57 68 65 6e 20 74 68 65  H12504} When the
17210 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17220 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
17230 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70  LITE_OK], the op
17240 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  eration.**      
17250 20 20 20 20 64 65 73 63 72 69 62 65 64 20 69 73      described is
17260 20 70 72 6f 63 65 73 73 65 64 20 6e 6f 72 6d 61   processed norma
17270 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  lly..**.** {H125
17280 30 35 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74  05} When the aut
17290 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
172a0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
172b0 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 20  _DENY], the.**  
172c0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
172d0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
172e0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
172f0 6c 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68  l that caused th
17300 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75  e.**          au
17310 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17320 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66  k to run shall f
17330 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ail.**          
17340 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f  with an [SQLITE_
17350 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64  ERROR] error cod
17360 65 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d  e and an error m
17370 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20  essage.**       
17380 20 20 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68     explaining th
17390 61 74 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  at access is den
173a0 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  ied..**.** {H125
173b0 30 36 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f  06} If the autho
173c0 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20  rizer code (the 
173d0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
173e0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a   the authorizer.
173f0 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
17400 62 61 63 6b 29 20 69 73 20 5b 53 51 4c 49 54 45  back) is [SQLITE
17410 5f 52 45 41 44 5d 20 61 6e 64 20 74 68 65 20 61  _READ] and the a
17420 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
17430 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  ck returns.**   
17440 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49         [SQLITE_I
17450 47 4e 4f 52 45 5d 2c 20 74 68 65 6e 20 74 68 65  GNORE], then the
17460 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
17470 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
17480 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ed to.**        
17490 20 20 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c 20    insert a NULL 
174a0 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
174b0 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
174c0 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
174d0 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  ve.**          b
174e0 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
174f0 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
17500 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
17510 20 7b 48 31 32 35 30 37 7d 20 49 66 20 74 68 65   {H12507} If the
17520 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65   authorizer code
17530 20 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65   (the 2nd parame
17540 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
17550 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  rizer.**        
17560 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 61    callback) is a
17570 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  nything other th
17580 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  an [SQLITE_READ]
17590 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
175a0 20 20 20 61 20 72 65 74 75 72 6e 20 6f 66 20 5b     a return of [
175b0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 68  SQLITE_IGNORE] h
175c0 61 73 20 74 68 65 20 73 61 6d 65 20 65 66 66 65  as the same effe
175d0 63 74 20 61 73 20 5b 53 51 4c 49 54 45 5f 44 45  ct as [SQLITE_DE
175e0 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  NY]..**.** {H125
175f0 31 30 7d 20 54 68 65 20 66 69 72 73 74 20 70 61  10} The first pa
17600 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
17610 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
17620 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a  ck is a copy of.
17630 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
17640 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
17650 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
17660 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
17670 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
17680 2a 2a 20 7b 48 31 32 35 31 31 7d 20 54 68 65 20  ** {H12511} The 
17690 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
176a0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
176b0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
176c0 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
176d0 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
176e0 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
176f0 69 66 69 65 73 20 74 68 65 20 70 61 72 74 69 63  ifies the partic
17700 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 20  ular action.**  
17710 20 20 20 20 20 20 20 20 74 6f 20 62 65 20 61 75          to be au
17720 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
17730 7b 48 31 32 35 31 32 7d 20 54 68 65 20 74 68 69  {H12512} The thi
17740 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
17750 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
17760 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 0a  he callback are.
17770 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
17780 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
17790 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
177a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 64  .**          add
177b0 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20  itional details 
177c0 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
177d0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
177e0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 30  d..**.** {H12520
177f0 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b  } Each call to [
17800 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
17810 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65 72 72 69  orizer()] overri
17820 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  des.**          
17830 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 69  any previously i
17840 6e 73 74 61 6c 6c 65 64 20 61 75 74 68 6f 72 69  nstalled authori
17850 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  zer..**.** {H125
17860 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f  21} A NULL autho
17870 72 69 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74  rizer means that
17880 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f   no authorizatio
17890 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  n.**          ca
178a0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
178b0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 32  d..**.** {H12522
178c0 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 61 75  } The default au
178d0 74 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c  thorizer is NULL
178e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
178f0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
17900 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
17910 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
17920 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
17930 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
17940 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
17950 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
17960 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
17970 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
17980 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
17990 43 6f 64 65 73 20 7b 48 31 32 35 39 30 7d 20 3c  Codes {H12590} <
179a0 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  H12500>.**.** Th
179b0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
179c0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
179d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
179e0 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a  function] must.*
179f0 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20  * return either 
17a00 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f  [SQLITE_OK] or o
17a10 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20  ne of these two 
17a20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64  constants in ord
17a30 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  er.** to signal 
17a40 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f  SQLite whether o
17a50 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e  r not the action
17a60 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20   is permitted.  
17a70 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  See the.** [sqli
17a80 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
17a90 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
17aa0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
17ab0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
17ac0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
17ad0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17ae0 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
17af0 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
17b00 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
17b10 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
17b20 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
17b30 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
17b40 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
17b50 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
17b60 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
17b70 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
17b80 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 20  er Action Codes 
17b90 7b 48 31 32 35 35 30 7d 20 3c 48 31 32 35 30 30  {H12550} <H12500
17ba0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  >.**.** The [sql
17bb0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
17bc0 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
17bd0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
17be0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
17bf0 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
17c00 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
17c10 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
17c20 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
17c30 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
17c40 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
17c50 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
17c60 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
17c70 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
17c80 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
17c90 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
17ca0 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
17cb0 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
17cc0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
17cd0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17ce0 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
17cf0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
17d00 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
17d10 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
17d20 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
17d30 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
17d40 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
17d50 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
17d60 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
17d70 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
17d80 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
17d90 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
17da0 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
17db0 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
17dc0 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
17dd0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
17de0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
17df0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
17e00 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
17e10 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
17e20 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
17e30 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
17e40 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74  ", "temp",.** et
17e50 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
17e60 65 2e 20 20 54 68 65 20 36 74 68 20 70 61 72 61  e.  The 6th para
17e70 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
17e80 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17e90 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
17ea0 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
17eb0 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
17ec0 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
17ed0 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
17ee0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
17ef0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
17f00 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
17f10 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
17f20 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
17f30 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   code..**.** INV
17f40 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
17f50 48 31 32 35 35 31 7d 20 54 68 65 20 73 65 63 6f  H12551} The seco
17f60 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
17f70 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  an.**          [
17f80 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
17f90 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
17fa0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73  zer callback] is
17fb0 20 61 6c 77 61 79 73 20 61 6e 20 69 6e 74 65 67   always an integ
17fc0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  er.**          [
17fd0 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75  SQLITE_COPY | au
17fe0 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 74  thorizer code] t
17ff0 68 61 74 20 73 70 65 63 69 66 69 65 73 20 77 68  hat specifies wh
18000 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  at action.**    
18010 20 20 20 20 20 20 69 73 20 62 65 69 6e 67 20 61        is being a
18020 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
18030 20 7b 48 31 32 35 35 32 7d 20 54 68 65 20 33 72   {H12552} The 3r
18040 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
18050 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 20  ters to the.**  
18060 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
18070 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
18080 7c 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  | authorization 
18090 63 61 6c 6c 62 61 63 6b 5d 0a 2a 2a 20 20 20 20  callback].**    
180a0 20 20 20 20 20 20 77 69 6c 6c 20 62 65 20 70 61        will be pa
180b0 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
180c0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
180d0 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ich.**          
180e0 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
180f0 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20  uthorizer code] 
18100 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
18110 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
18120 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 33 7d 20  .**.** {H12553} 
18130 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
18140 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  r to the.**     
18150 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65       [sqlite3_se
18160 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
18170 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
18180 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d 65 0a  ck] is the name.
18190 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  **          of t
181a0 68 65 20 64 61 74 61 62 61 73 65 20 28 65 78 61  he database (exa
181b0 6d 70 6c 65 3a 20 22 6d 61 69 6e 22 2c 20 22 74  mple: "main", "t
181c0 65 6d 70 22 2c 20 65 74 63 2e 29 20 69 66 20 61  emp", etc.) if a
181d0 70 70 6c 69 63 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  pplicable..**.**
181e0 20 7b 48 31 32 35 35 34 7d 20 54 68 65 20 36 74   {H12554} The 6t
181f0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
18200 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
18210 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
18220 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
18230 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73  zer callback] is
18240 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20   the name.**    
18250 20 20 20 20 20 20 6f 66 20 74 68 65 20 69 6e 6e        of the inn
18260 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
18270 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
18280 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
18290 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
182a0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
182b0 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
182c0 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
182d0 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
182e0 2a 20 20 20 20 20 20 20 20 20 20 74 6f 70 2d 6c  *          top-l
182f0 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
18300 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
18310 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18320 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
18330 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
18340 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
18350 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18360 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
18370 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
18380 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
18390 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
183a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
183b0 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
183c0 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
183d0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
183e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
183f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
18400 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
18410 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
18420 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
18430 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
18440 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
18450 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
18460 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
18470 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
18480 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
18490 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
184a0 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
184b0 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
184c0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
184d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
184e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
184f0 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
18500 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
18510 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
18520 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18530 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
18540 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
18550 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
18560 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
18570 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
18580 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
18590 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
185a0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
185b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
185c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
185d0 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
185e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
185f0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
18600 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18610 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18620 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
18630 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
18640 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
18650 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
18660 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18670 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
18680 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
18690 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
186a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
186b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
186c0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
186d0 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
186e0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
186f0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
18700 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18710 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
18720 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
18730 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18740 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18750 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18760 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
18770 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
18780 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
18790 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
187a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
187b0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
187c0 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
187d0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
187e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
187f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18800 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
18810 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
18820 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
18830 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
18840 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18850 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
18860 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
18870 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
18880 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
188a0 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
188b0 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
188c0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
188d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
188e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
188f0 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
18900 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
18910 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
18920 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
18930 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
18940 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
18950 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
18960 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
18970 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
18980 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
18990 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
189a0 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
189b0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
189c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
189d0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
189e0 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
189f0 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  22   /* NULL    
18a00 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
18a10 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18a20 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
18a30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
18a40 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
18a50 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
18a60 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
18a70 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
18a80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
18a90 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
18aa0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18ab0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18ac0 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
18ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
18ae0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
18af0 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
18b00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18b10 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
18b20 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
18b30 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
18b40 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
18b50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18b60 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
18b70 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
18b80 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
18b90 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
18ba0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18bb0 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
18bc0 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
18bd0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
18be0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18bf0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18c00 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
18c10 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
18c20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18c30 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
18c40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18c50 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
18c60 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
18c70 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18c80 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
18c90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18ca0 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
18cb0 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 46         31   /* F
18cc0 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 4e  unction Name   N
18cd0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18ce0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18cf0 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
18d00 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
18d10 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
18d20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18d30 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
18d40 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
18d50 20 7b 48 31 32 32 38 30 7d 20 3c 53 36 30 34 30   {H12280} <S6040
18d60 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
18d70 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
18d80 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
18d90 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
18da0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
18db0 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
18dc0 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
18dd0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
18de0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  s..**.** The cal
18df0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
18e00 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
18e10 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
18e20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
18e30 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
18e40 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
18e50 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
18e60 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
18e70 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  )]..** The callb
18e80 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54  ack returns a UT
18e90 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
18ea0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
18eb0 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68  nt text.** as th
18ec0 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
18ed0 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
18ee0 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  ng.  Additional 
18ef0 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a  callbacks occur.
18f00 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
18f10 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
18f20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
18f30 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
18f40 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
18f50 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
18f60 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
18f70 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
18f80 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  er..**.** The ca
18f90 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
18fa0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
18fb0 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
18fc0 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
18fd0 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
18fe0 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 54  ent finishes.  T
18ff0 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
19000 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
19010 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
19020 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
19030 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
19040 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
19050 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
19060 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
19070 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20  k to run..**.** 
19080 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  The sqlite3_prof
19090 69 6c 65 28 29 20 41 50 49 20 69 73 20 63 75 72  ile() API is cur
190a0 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65  rently considere
190b0 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
190c0 6e 64 0a 2a 2a 20 69 73 20 73 75 62 6a 65 63 74  nd.** is subject
190d0 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72 65   to change or re
190e0 6d 6f 76 61 6c 20 69 6e 20 61 20 66 75 74 75 72  moval in a futur
190f0 65 20 72 65 6c 65 61 73 65 2e 0a 2a 2a 0a 2a 2a  e release..**.**
19100 20 54 68 65 20 74 72 69 67 67 65 72 20 72 65 70   The trigger rep
19110 6f 72 74 69 6e 67 20 66 65 61 74 75 72 65 20 6f  orting feature o
19120 66 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c  f the trace call
19130 62 61 63 6b 20 69 73 20 63 6f 6e 73 69 64 65 72  back is consider
19140 65 64 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74  ed.** experiment
19150 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63  al and is subjec
19160 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72  t to change or r
19170 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65  emoval in future
19180 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 20 46 75   releases..** Fu
19190 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
191a0 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c   SQLite might al
191b0 73 6f 20 61 64 64 20 6e 65 77 20 74 72 61 63 65  so add new trace
191c0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6e 76   callback.** inv
191d0 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  ocations..**.** 
191e0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
191f0 2a 20 7b 48 31 32 32 38 31 7d 20 54 68 65 20 63  * {H12281} The c
19200 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
19210 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b   registered by [
19220 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d  sqlite3_trace()]
19230 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
19240 77 68 65 6e 65 76 65 72 20 61 6e 20 53 51 4c 20  whenever an SQL 
19250 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
19260 62 65 67 69 6e 73 20 74 6f 20 65 78 65 63 75 74  begins to execut
19270 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  e and.**        
19280 20 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 69    whenever a tri
19290 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 20  gger subprogram 
192a0 66 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20  first begins to 
192b0 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  run..**.** {H122
192c0 38 32 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  82} Each call to
192d0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
192e0 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  )] overrides the
192f0 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20   previously.**  
19300 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
19310 65 64 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ed trace callbac
19320 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 33  k..**.** {H12283
19330 7d 20 41 20 4e 55 4c 4c 20 74 72 61 63 65 20 63  } A NULL trace c
19340 61 6c 6c 62 61 63 6b 20 64 69 73 61 62 6c 65 73  allback disables
19350 20 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   tracing..**.** 
19360 7b 48 31 32 32 38 34 7d 20 54 68 65 20 66 69 72  {H12284} The fir
19370 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
19380 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  he trace callbac
19390 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  k is a copy of.*
193a0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 70  *          the p
193b0 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73  ointer which was
193c0 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e   the 3rd argumen
193d0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72  t to [sqlite3_tr
193e0 61 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ace()]..**.** {H
193f0 31 32 32 38 35 7d 20 54 68 65 20 73 65 63 6f 6e  12285} The secon
19400 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
19410 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  e trace callback
19420 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20   is a.**        
19430 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
19440 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 63  d UTF-8 string c
19450 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6f 72  ontaining the or
19460 69 67 69 6e 61 6c 20 74 65 78 74 0a 2a 2a 20 20  iginal text.**  
19470 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 53          of the S
19480 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
19490 69 74 20 77 61 73 20 70 61 73 73 65 64 20 69 6e  it was passed in
194a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
194b0 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20  are_v2()].**    
194c0 20 20 20 20 20 20 6f 72 20 74 68 65 20 65 71 75        or the equ
194d0 69 76 61 6c 65 6e 74 2c 20 6f 72 20 61 6e 20 53  ivalent, or an S
194e0 51 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e 64 69 63  QL comment indic
194f0 61 74 69 6e 67 20 74 68 65 20 62 65 67 69 6e 6e  ating the beginn
19500 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
19510 6f 66 20 61 20 74 72 69 67 67 65 72 20 73 75 62  of a trigger sub
19520 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b  program..**.** {
19530 48 31 32 32 38 37 7d 20 54 68 65 20 63 61 6c 6c  H12287} The call
19540 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
19550 67 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c  gistered by [sql
19560 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20  ite3_profile()] 
19570 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20  is invoked.**   
19580 20 20 20 20 20 20 20 61 73 20 65 61 63 68 20 53         as each S
19590 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
195a0 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ishes..**.** {H1
195b0 32 32 38 38 7d 20 54 68 65 20 66 69 72 73 74 20  2288} The first 
195c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
195d0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
195e0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  k is a copy of.*
195f0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 33  *          the 3
19600 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
19610 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  [sqlite3_profile
19620 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  ()]..**.** {H122
19630 38 39 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70  89} The second p
19640 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
19650 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
19660 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20   is a.**        
19670 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
19680 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  d UTF-8 string t
19690 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  hat contains the
196a0 20 63 6f 6d 70 6c 65 74 65 20 74 65 78 74 20 6f   complete text o
196b0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
196c0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
196d0 61 73 20 69 74 20 77 61 73 20 70 72 6f 63 65 73  as it was proces
196e0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
196f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a  prepare_v2()].**
19700 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65            or the
19710 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a   equivalent..**.
19720 2a 2a 20 7b 48 31 32 32 39 30 7d 20 54 68 65 20  ** {H12290} The 
19730 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
19740 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63  to the profile c
19750 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 65 73  allback is an es
19760 74 69 6d 61 74 65 0a 2a 2a 20 20 20 20 20 20 20  timate.**       
19770 20 20 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72     of the number
19780 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 20   of nanoseconds 
19790 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
197a0 6d 65 20 72 65 71 75 69 72 65 64 20 74 6f 0a 2a  me required to.*
197b0 2a 20 20 20 20 20 20 20 20 20 20 72 75 6e 20 74  *          run t
197c0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
197d0 20 66 72 6f 6d 20 73 74 61 72 74 20 74 6f 20 66   from start to f
197e0 69 6e 69 73 68 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  inish..*/.void *
197f0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
19800 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54  lite3*, void(*xT
19810 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
19820 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
19830 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
19840 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
19850 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
19860 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
19870 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
19880 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
19890 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
198a0 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
198b0 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 31  Callbacks {H1291
198c0 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a  0} <S60400>.**.*
198d0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63  * This routine c
198e0 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c  onfigures a call
198f0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20  back function - 
19900 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20  the.** progress 
19910 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20  callback - that 
19920 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  is invoked perio
19930 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
19940 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63  ong.** running c
19950 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
19960 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
19970 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a  e3_step()] and.*
19980 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
19990 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61  able()].  An exa
199a0 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
199b0 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
199c0 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
199d0 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
199e0 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
199f0 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72  .** If the progr
19a00 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
19a10 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
19a20 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
19a30 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
19a40 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
19a50 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
19a60 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
19a70 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
19a80 20 47 55 49 20 64 69 61 6c 6f 67 20 62 6f 78 2e   GUI dialog box.
19a90 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
19aa0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 31  S:.**.** {H12911
19ab0 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  } The callback f
19ac0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
19ad0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
19ae0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
19af0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
19b00 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
19b10 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
19b20 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
19b30 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
19b40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
19b50 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 32 7d 20 54  **.** {H12912} T
19b60 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
19b70 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
19b80 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20 4e  once for every N
19b90 20 76 69 72 74 75 61 6c 0a 2a 2a 20 20 20 20 20   virtual.**     
19ba0 20 20 20 20 20 6d 61 63 68 69 6e 65 20 6f 70 63       machine opc
19bb0 6f 64 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  odes, where N is
19bc0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
19bd0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20  ment to.**      
19be0 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33      the [sqlite3
19bf0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
19c00 72 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 72  r()] call that r
19c10 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20  egistered.**    
19c20 20 20 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61        the callba
19c30 63 6b 2e 20 20 49 66 20 4e 20 69 73 20 6c 65 73  ck.  If N is les
19c40 73 20 74 68 61 6e 20 31 2c 20 73 71 6c 69 74 65  s than 1, sqlite
19c50 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
19c60 65 72 28 29 0a 2a 2a 20 20 20 20 20 20 20 20 20  er().**         
19c70 20 61 63 74 73 20 61 73 20 69 66 20 61 20 4e 55   acts as if a NU
19c80 4c 4c 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  LL progress hand
19c90 6c 65 72 20 68 61 64 20 62 65 65 6e 20 73 70 65  ler had been spe
19ca0 63 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  cified..**.** {H
19cb0 31 32 39 31 33 7d 20 54 68 65 20 70 72 6f 67 72  12913} The progr
19cc0 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 74 73  ess callback its
19cd0 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66 69 65  elf is identifie
19ce0 64 20 62 79 20 74 68 65 20 74 68 69 72 64 0a 2a  d by the third.*
19cf0 2a 20 20 20 20 20 20 20 20 20 20 61 72 67 75 6d  *          argum
19d00 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70  ent to sqlite3_p
19d10 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
19d20 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 34  )..**.** {H12914
19d30 7d 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  } The fourth arg
19d40 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
19d50 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
19d60 72 28 29 20 69 73 20 61 0a 2a 2a 20 20 20 20 20  r() is a.**     
19d70 20 20 20 20 20 76 6f 69 64 20 70 6f 69 6e 74 65       void pointe
19d80 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
19d90 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
19da0 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75  k.**          fu
19db0 6e 63 74 69 6f 6e 20 65 61 63 68 20 74 69 6d 65  nction each time
19dc0 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a   it is invoked..
19dd0 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 35 7d 20 49  **.** {H12915} I
19de0 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  f a call to [sql
19df0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 73  ite3_step()] res
19e00 75 6c 74 73 20 69 6e 20 66 65 77 65 72 20 74 68  ults in fewer th
19e10 61 6e 20 4e 20 6f 70 63 6f 64 65 73 0a 2a 2a 20  an N opcodes.** 
19e20 20 20 20 20 20 20 20 20 20 62 65 69 6e 67 20 65           being e
19e30 78 65 63 75 74 65 64 2c 20 74 68 65 6e 20 74 68  xecuted, then th
19e40 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
19e50 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e 76  ack is never inv
19e60 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  oked..**.** {H12
19e70 39 31 36 7d 20 45 76 65 72 79 20 63 61 6c 6c 20  916} Every call 
19e80 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67  to [sqlite3_prog
19e90 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a  ress_handler()].
19ea0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 72  **          over
19eb0 77 72 69 74 65 73 20 61 6e 79 20 70 72 65 76 69  writes any previ
19ec0 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64  ously registered
19ed0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
19ee0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 37  r..**.** {H12917
19ef0 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73  } If the progres
19f00 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  s handler callba
19f10 63 6b 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  ck is NULL then 
19f20 6e 6f 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 20  no progress.**  
19f30 20 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20          handler 
19f40 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
19f50 2a 20 7b 48 31 32 39 31 38 7d 20 49 66 20 74 68  * {H12918} If th
19f60 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
19f70 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 72 65  ack returns a re
19f80 73 75 6c 74 20 6f 74 68 65 72 20 74 68 61 6e 20  sult other than 
19f90 30 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  0, then.**      
19fa0 20 20 20 20 74 68 65 20 62 65 68 61 76 69 6f 72      the behavior
19fb0 20 69 73 20 61 20 69 66 20 5b 73 71 6c 69 74 65   is a if [sqlite
19fc0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20 68  3_interrupt()] h
19fd0 61 64 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a  ad been called..
19fe0 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 53 33 30  **          <S30
19ff0 35 30 30 3e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  500>.*/.void sql
1a000 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1a010 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
1a020 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
1a030 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
1a040 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
1a050 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
1a060 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b  ase Connection {
1a070 48 31 32 37 30 30 7d 20 3c 53 34 30 32 30 30 3e  H12700} <S40200>
1a080 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1a090 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
1a0a0 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
1a0b0 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73  le whose name is
1a0c0 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a   given by the.**
1a0d0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1a0e0 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61 6d 65  nt. The filename
1a0f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
1a100 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
1a110 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
1a120 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1a130 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
1a140 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
1a150 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
1a160 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
1a170 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 41 20  te3_open16(). A 
1a180 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1a190 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20  tion] handle is 
1a1a0 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72  usually.** retur
1a1b0 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
1a1c0 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  en if an error o
1a1d0 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79  ccurs.  The only
1a1e0 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68   exception is th
1a1f0 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  at.** if SQLite 
1a200 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
1a210 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
1a220 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65  hold the [sqlite
1a230 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20  3] object,.** a 
1a240 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69  NULL will be wri
1a250 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20  tten into *ppDb 
1a260 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69  instead of a poi
1a270 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
1a280 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e  ite3].** object.
1a290 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
1a2a0 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f   is opened (and/
1a2b0 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63  or created) succ
1a2c0 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a  essfully, then.*
1a2d0 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  * [SQLITE_OK] is
1a2e0 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
1a2f0 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
1a300 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
1a310 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  d.  The.** [sqli
1a320 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
1a330 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1a340 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
1a350 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
1a360 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
1a370 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
1a380 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
1a390 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rror..**.** The 
1a3a0 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
1a3b0 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
1a3c0 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20  e will be UTF-8 
1a3d0 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  if.** sqlite3_op
1a3e0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
1a3f0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c  open_v2() is cal
1a400 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31  led and.** UTF-1
1a410 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
1a420 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71  byte order if sq
1a430 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69  lite3_open16() i
1a440 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68  s used..**.** Wh
1a450 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20  ether or not an 
1a460 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65  error occurs whe
1a470 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20  n it is opened, 
1a480 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73  resources.** ass
1a490 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
1a4a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1a4b0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68  ction] handle sh
1a4c0 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
1a4d0 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69   by.** passing i
1a4e0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  t to [sqlite3_cl
1a4f0 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
1a500 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
1a510 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
1a520 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1a530 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b  ) interface work
1a540 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f  s like sqlite3_o
1a550 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  pen().** except 
1a560 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20  that it accepts 
1a570 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70  two additional p
1a580 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64  arameters for ad
1a590 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c  ditional control
1a5a0 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77  .** over the new
1a5b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a5c0 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67 73  tion.  The flags
1a5d0 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 74   parameter can t
1a5e0 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
1a5f0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
1a600 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
1a610 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
1a620 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
1a630 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1a640 20 66 6c 61 67 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c   flag:.**.** <dl
1a650 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45  >.** <dt>[SQLITE
1a660 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
1a670 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1a680 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1a690 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
1a6a0 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
1a6b0 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
1a6c0 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
1a6d0 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
1a6e0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  turned.</dd>.**.
1a6f0 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f  ** <dt>[SQLITE_O
1a700 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f  PEN_READWRITE]</
1a710 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
1a720 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1a730 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
1a740 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
1a750 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e  sible, or readin
1a760 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65  g.** only if the
1a770 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
1a780 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
1a790 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1a7a0 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20  .  In either.** 
1a7b0 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
1a7c0 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65  e must already e
1a7d0 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20  xist, otherwise 
1a7e0 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
1a7f0 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  rned.</dd>.**.**
1a800 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45   <dt>[SQLITE_OPE
1a810 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
1a820 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1a830 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
1a840 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1a850 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
1a860 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
1a870 61 6e 64 20 69 73 20 63 72 65 61 74 65 73 20 69  and is creates i
1a880 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  t if.** it does 
1a890 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
1a8a0 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
1a8b0 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
1a8c0 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
1a8d0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1a8e0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
1a8f0 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20  en16().</dd>.** 
1a900 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
1a910 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
1a920 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
1a930 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
1a940 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
1a950 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
1a960 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ove or one of th
1a970 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  e combinations s
1a980 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69  hown above combi
1a990 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ned.** with the 
1a9a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1a9b0 55 54 45 58 5d 20 66 6c 61 67 2c 20 74 68 65 6e  UTEX] flag, then
1a9c0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1a9d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
1a9e0 2a 20 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * If the [SQLITE
1a9f0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
1aa00 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e  lag is set, then
1aa10 20 6d 75 74 65 78 65 73 20 6f 6e 20 74 68 65 0a   mutexes on the.
1aa20 2a 2a 20 6f 70 65 6e 65 64 20 5b 64 61 74 61 62  ** opened [datab
1aa30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1aa40 61 72 65 20 64 69 73 61 62 6c 65 64 20 61 6e 64  are disabled and
1aa50 20 74 68 65 20 61 70 70 6c 69 61 74 69 6f 6e 20   the appliation 
1aa60 6d 75 73 74 0a 2a 2a 20 69 6e 73 75 72 65 20 74  must.** insure t
1aa70 68 61 74 20 61 63 63 65 73 73 20 74 6f 20 74 68  hat access to th
1aa80 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1aa90 65 63 74 69 6f 6e 5d 20 61 6e 64 20 69 74 73 20  ection] and its 
1aaa0 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 5b 70  associated.** [p
1aab0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1aac0 74 73 5d 20 69 73 20 73 65 72 69 61 6c 69 7a 65  ts] is serialize
1aad0 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
1aae0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
1aaf0 61 67 0a 2a 2a 20 69 73 20 74 68 65 20 64 65 66  ag.** is the def
1ab00 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73  ault behavior is
1ab10 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6e 66 69   SQLite is confi
1ab20 67 75 72 65 64 20 75 73 69 6e 67 20 74 68 65 0a  gured using the.
1ab30 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
1ab40 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 20 6f  G_MULTITHREAD] o
1ab50 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
1ab60 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
1ab70 70 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 5b 73 71  ptions.** to [sq
1ab80 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
1ab90 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50    The [SQLITE_OP
1aba0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
1abb0 20 6f 6e 6c 79 20 6d 61 6b 65 73 20 61 0a 2a 2a   only makes a.**
1abc0 20 64 69 66 66 65 72 65 6e 63 65 20 77 68 65 6e   difference when
1abd0 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 69 74   SQLite is in it
1abe0 73 20 64 65 66 61 75 6c 74 20 5b 53 51 4c 49 54  s default [SQLIT
1abf0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
1ac00 5a 45 44 5d 20 6d 6f 64 65 2e 0a 2a 2a 0a 2a 2a  ZED] mode..**.**
1ac10 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   If the filename
1ac20 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
1ac30 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
1ac40 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
1ac50 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
1ac60 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
1ac70 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
1ac80 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
1ac90 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
1aca0 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
1acb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1acc0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
1acd0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
1ace0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
1acf0 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
1ad00 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
1ad10 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
1ad20 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
1ad30 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
1ad40 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
1ad50 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
1ad60 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
1ad70 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
1ad80 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
1ad90 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
1ada0 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
1adb0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
1adc0 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
1add0 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
1ade0 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
1adf0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  .**.** If the fi
1ae00 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
1ae10 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
1ae20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
1ae30 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
1ae40 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1ae50 20 63 72 65 61 74 65 64 2e 20 20 54 68 69 73 20   created.  This 
1ae60 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
1ae70 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
1ae80 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
1ae90 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
1aea0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1aeb0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
1aec0 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68  **.** The fourth
1aed0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1aee0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1aef0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1af00 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
1af10 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
1af20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
1af30 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
1af40 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74  erface that.** t
1af50 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
1af60 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
1af70 64 20 75 73 65 2e 20 20 49 66 20 74 68 65 20 66  d use.  If the f
1af80 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1af90 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
1afa0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
1afb0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
1afc0 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
1afd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
1afe0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
1aff0 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
1b000 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
1b010 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
1b020 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
1b030 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1b040 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1b050 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
1b060 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
1b070 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
1b080 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
1b090 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
1b0a0 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
1b0b0 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
1b0c0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
1b0d0 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
1b0e0 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
1b0f0 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
1b100 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
1b110 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
1b120 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1b130 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 31 7d 20 54  **.** {H12701} T
1b140 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
1b150 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1b160 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
1b170 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1b180 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
1b190 65 72 66 61 63 65 73 20 63 72 65 61 74 65 20 61  erfaces create a
1b1a0 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20   new.**         
1b1b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b1c0 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65  ction] associate
1b1d0 64 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  d with.**       
1b1e0 20 20 20 74 68 65 20 64 61 74 61 62 61 73 65 20     the database 
1b1f0 66 69 6c 65 20 67 69 76 65 6e 20 69 6e 20 74 68  file given in th
1b200 65 69 72 20 66 69 72 73 74 20 70 61 72 61 6d 65  eir first parame
1b210 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ter..**.** {H127
1b220 30 32 7d 20 54 68 65 20 66 69 6c 65 6e 61 6d 65  02} The filename
1b230 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
1b240 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
1b250 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f  8.**          fo
1b260 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  r [sqlite3_open(
1b270 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1b280 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61  open_v2()] and a
1b290 73 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20  s UTF-16.**     
1b2a0 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74 69       in the nati
1b2b0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f  ve byte order fo
1b2c0 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
1b2d0 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  6()]..**.** {H12
1b2e0 37 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 75  703} A successfu
1b2f0 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
1b300 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1b310 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
1b320 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  6()],.**        
1b330 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70    or [sqlite3_op
1b340 65 6e 5f 76 32 28 29 5d 20 77 72 69 74 65 73 20  en_v2()] writes 
1b350 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
1b360 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ew.**          [
1b370 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b380 69 6f 6e 5d 20 69 6e 74 6f 20 2a 70 70 44 62 2e  ion] into *ppDb.
1b390 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 34 7d 20  .**.** {H12704} 
1b3a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
1b3b0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
1b3c0 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a  pen16()], and.**
1b3d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1b3e0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
1b3f0 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20  terfaces return 
1b400 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e  [SQLITE_OK] upon
1b410 20 73 75 63 63 65 73 73 2c 0a 2a 2a 20 20 20 20   success,.**    
1b420 20 20 20 20 20 20 6f 72 20 61 6e 20 61 70 70 72        or an appr
1b430 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
1b440 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e  ode] on failure.
1b450 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 36 7d 20  .**.** {H12706} 
1b460 54 68 65 20 64 65 66 61 75 6c 74 20 74 65 78 74  The default text
1b470 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20   encoding for a 
1b480 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 72 65  new database cre
1b490 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ated using.**   
1b4a0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1b4b0 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69  open()] or [sqli
1b4c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77  te3_open_v2()] w
1b4d0 69 6c 6c 20 62 65 20 55 54 46 2d 38 2e 0a 2a 2a  ill be UTF-8..**
1b4e0 0a 2a 2a 20 7b 48 31 32 37 30 37 7d 20 54 68 65  .** {H12707} The
1b4f0 20 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e   default text en
1b500 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77  coding for a new
1b510 20 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65   database create
1b520 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
1b530 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65      [sqlite3_ope
1b540 6e 31 36 28 29 5d 20 77 69 6c 6c 20 62 65 20 55  n16()] will be U
1b550 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  TF-16..**.** {H1
1b560 32 37 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  2709} The [sqlit
1b570 65 33 5f 6f 70 65 6e 28 46 2c 44 29 5d 20 69 6e  e3_open(F,D)] in
1b580 74 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76  terface is equiv
1b590 61 6c 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20  alent to.**     
1b5a0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70       [sqlite3_op
1b5b0 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 30 29 5d 20  en_v2(F,D,G,0)] 
1b5c0 77 68 65 72 65 20 74 68 65 20 47 20 70 61 72 61  where the G para
1b5d0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20  meter is.**     
1b5e0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45       [SQLITE_OPE
1b5f0 4e 5f 52 45 41 44 57 52 49 54 45 5d 7c 5b 53 51  N_READWRITE]|[SQ
1b600 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1b610 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 31  ]..**.** {H12711
1b620 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d  } If the G param
1b630 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1b640 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56  _open_v2(F,D,G,V
1b650 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a  )] contains the.
1b660 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20  **          bit 
1b670 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50  value [SQLITE_OP
1b680 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 74 68 65  EN_READONLY] the
1b690 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
1b6a0 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20  s opened.**     
1b6b0 20 20 20 20 20 66 6f 72 20 72 65 61 64 69 6e 67       for reading
1b6c0 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   only..**.** {H1
1b6d0 32 37 31 32 7d 20 49 66 20 74 68 65 20 47 20 70  2712} If the G p
1b6e0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
1b6f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
1b700 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20  ,G,V)] contains 
1b710 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1b720 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  bit value [SQLIT
1b730 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1b740 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  ] then the datab
1b750 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a  ase is opened.**
1b760 20 20 20 20 20 20 20 20 20 20 72 65 61 64 69 6e            readin
1b770 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
1b780 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 66 6f   possible, or fo
1b790 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69  r reading only i
1b7a0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
1b7b0 20 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20    file is write 
1b7c0 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
1b7d0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1b7e0 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 33  m..**.** {H12713
1b7f0 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d  } If the G param
1b800 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1b810 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c 47 2c 56  _open(v2(F,D,G,V
1b820 29 5d 20 6f 6d 69 74 73 20 74 68 65 0a 2a 2a 20  )] omits the.** 
1b830 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c           bit val
1b840 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ue [SQLITE_OPEN_
1b850 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20  CREATE] and the 
1b860 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
1b870 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72  t.**          pr
1b880 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20  eviously exist, 
1b890 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
1b8a0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  rned..**.** {H12
1b8b0 37 31 34 7d 20 49 66 20 74 68 65 20 47 20 70 61  714} If the G pa
1b8c0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
1b8d0 74 65 33 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c  te3_open(v2(F,D,
1b8e0 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74  G,V)] contains t
1b8f0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  he.**          b
1b900 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  it value [SQLITE
1b910 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e  _OPEN_CREATE] an
1b920 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  d the database d
1b930 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20  oes not.**      
1b940 20 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65      previously e
1b950 78 69 73 74 2c 20 74 68 65 6e 20 61 6e 20 61 74  xist, then an at
1b960 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
1b970 20 63 72 65 61 74 65 20 61 6e 64 0a 2a 2a 20 20   create and.**  
1b980 20 20 20 20 20 20 20 20 69 6e 69 74 69 61 6c 69          initiali
1b990 7a 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ze the database.
1b9a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 37 7d 20  .**.** {H12717} 
1b9b0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1b9c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
1b9d0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1b9e0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1b9f0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
1ba00 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1ba10 32 28 29 5d 20 69 73 20 22 3a 6d 65 6d 6f 72 79  2()] is ":memory
1ba20 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69 76  :", then an priv
1ba30 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ate,.**         
1ba40 20 65 70 68 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d   ephemeral, in-m
1ba50 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 69  emory database i
1ba60 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
1ba70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a  e connection..**
1ba80 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e            <todo>
1ba90 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  Is SQLITE_OPEN_C
1baa0 52 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45  REATE|SQLITE_OPE
1bab0 4e 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75  N_READWRITE requ
1bac0 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ired.**         
1bad0 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
1bae0 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a  _v2()?</todo>.**
1baf0 0a 2a 2a 20 7b 48 31 32 37 31 39 7d 20 49 66 20  .** {H12719} If 
1bb00 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
1bb10 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79  NULL or an empty
1bb20 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
1bb30 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20  private,.**     
1bb40 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c 20 6f       ephemeral o
1bb50 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
1bb60 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
1bb70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f  .**          <to
1bb80 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 45  do>Is SQLITE_OPE
1bb90 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45 5f  N_CREATE|SQLITE_
1bba0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 72  OPEN_READWRITE r
1bbb0 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 20  equired.**      
1bbc0 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f      in sqlite3_o
1bbd0 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e  pen_v2()?</todo>
1bbe0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32 31 7d 20  .**.** {H12721} 
1bbf0 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
1bc00 6e 6e 65 63 74 69 6f 6e 5d 20 63 72 65 61 74 65  nnection] create
1bc10 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d by [sqlite3_op
1bc20 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 0a  en_v2(F,D,G,V)].
1bc30 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c  **          will
1bc40 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
1bc50 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 64  3_vfs] object id
1bc60 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
1bc70 56 20 70 61 72 61 6d 65 74 65 72 2c 0a 2a 2a 20  V parameter,.** 
1bc80 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
1bc90 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1bca0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 66 20  _vfs] object if 
1bcb0 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  V is a NULL poin
1bcc0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ter..**.** {H127
1bcd0 32 33 7d 20 54 77 6f 20 5b 64 61 74 61 62 61 73  23} Two [databas
1bce0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 77  e connections] w
1bcf0 69 6c 6c 20 73 68 61 72 65 20 61 20 63 6f 6d 6d  ill share a comm
1bd00 6f 6e 20 63 61 63 68 65 20 69 66 20 62 6f 74 68  on cache if both
1bd10 20 77 65 72 65 0a 2a 2a 20 20 20 20 20 20 20 20   were.**        
1bd20 20 20 6f 70 65 6e 65 64 20 77 69 74 68 20 74 68    opened with th
1bd30 65 20 73 61 6d 65 20 56 46 53 20 77 68 69 6c 65  e same VFS while
1bd40 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
1bd50 6f 64 65 5d 20 77 61 73 20 65 6e 61 62 6c 65 64  ode] was enabled
1bd60 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
1bd70 20 69 66 20 62 6f 74 68 20 66 69 6c 65 6e 61 6d   if both filenam
1bd80 65 73 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c  es compare equal
1bd90 20 75 73 69 6e 67 20 6d 65 6d 63 6d 70 28 29 20   using memcmp() 
1bda0 61 66 74 65 72 20 68 61 76 69 6e 67 20 62 65 65  after having bee
1bdb0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72  n.**          pr
1bdc0 6f 63 65 73 73 65 64 20 62 79 20 74 68 65 20 5b  ocessed by the [
1bdd0 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 78 46  sqlite3_vfs | xF
1bde0 75 6c 6c 50 61 74 68 6e 61 6d 65 5d 20 6d 65 74  ullPathname] met
1bdf0 68 6f 64 20 6f 66 20 74 68 65 20 56 46 53 2e 0a  hod of the VFS..
1be00 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
1be10 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
1be20 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
1be30 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
1be40 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
1be50 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
1be60 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
1be70 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
1be80 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
1be90 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
1bea0 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
1beb0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
1bec0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
1bed0 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
1bee0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
1bef0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
1bf00 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
1bf10 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
1bf20 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
1bf30 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
1bf40 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
1bf50 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
1bf60 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
1bf70 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
1bf80 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
1bf90 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
1bfa0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1bfb0 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
1bfc0 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
1bfd0 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
1bfe0 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
1bff0 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
1c000 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
1c010 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
1c020 73 20 7b 48 31 32 38 30 30 7d 20 3c 53 36 30 32  s {H12800} <S602
1c030 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
1c040 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
1c050 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1c060 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
1c070 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a  esult code] or.*
1c080 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
1c090 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  lt code] for the
1c0a0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69   most recent fai
1c0b0 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  led sqlite3_* AP
1c0c0 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69  I call.** associ
1c0d0 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74  ated with a [dat
1c0e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c0f0 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50  ]. If a prior AP
1c100 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a  I call failed.**
1c110 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65   but the most re
1c120 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75  cent API call su
1c130 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74  cceeded, the ret
1c140 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a  urn value from.*
1c150 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  * sqlite3_errcod
1c160 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
1c170 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1c180 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
1c190 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
1c1a0 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
1c1b0 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
1c1c0 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
1c1d0 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
1c1e0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
1c1f0 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
1c200 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  vely..** Memory 
1c210 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
1c220 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
1c230 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
1c240 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61  rnally..** The a
1c250 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20  pplication does 
1c260 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72  not need to worr
1c270 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20  y about freeing 
1c280 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48  the result..** H
1c290 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f  owever, the erro
1c2a0 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62  r string might b
1c2b0 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
1c2c0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a   deallocated by.
1c2d0 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ** subsequent ca
1c2e0 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c  lls to other SQL
1c2f0 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75  ite interface fu
1c300 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  nctions..**.** I
1c310 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
1c320 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
1c330 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
1c340 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
1c350 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
1c360 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
1c370 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
1c380 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
1c390 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
1c3a0 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
1c3b0 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
1c3c0 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  set..**.** INVAR
1c3d0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
1c3e0 32 38 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2801} The [sqlit
1c3f0 65 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69  e3_errcode(D)] i
1c400 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1c410 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20   the numeric.** 
1c420 20 20 20 20 20 20 20 20 20 5b 72 65 73 75 6c 74           [result
1c430 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e   code] or [exten
1c440 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
1c450 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
1c460 63 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20  cently.**       
1c470 20 20 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66     failed interf
1c480 61 63 65 20 63 61 6c 6c 20 61 73 73 6f 63 69 61  ace call associa
1c490 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
1c4a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c4b0 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  n] D..**.** {H12
1c4c0 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  803} The [sqlite
1c4d0 33 5f 65 72 72 6d 73 67 28 44 29 5d 20 61 6e 64  3_errmsg(D)] and
1c4e0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1c4f0 31 36 28 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  16(D)].**       
1c500 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65     interfaces re
1c510 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
1c520 67 75 61 67 65 20 74 65 78 74 20 74 68 61 74 20  guage text that 
1c530 64 65 73 63 72 69 62 65 73 0a 2a 2a 20 20 20 20  describes.**    
1c540 20 20 20 20 20 20 74 68 65 20 65 72 72 6f 72 20        the error 
1c550 69 6e 20 74 68 65 20 6d 6f 73 74 6c 79 20 72 65  in the mostly re
1c560 63 65 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e  cently failed in
1c570 74 65 72 66 61 63 65 20 63 61 6c 6c 2c 0a 2a 2a  terface call,.**
1c580 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 65            encode
1c590 64 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  d as either UTF-
1c5a0 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
1c5b0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
1c5c0 7b 48 31 32 38 30 37 7d 20 54 68 65 20 73 74 72  {H12807} The str
1c5d0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1c5e0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1c5f0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1c600 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20  _errmsg16()].** 
1c610 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61 6c           are val
1c620 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  id until the nex
1c630 74 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  t SQLite interfa
1c640 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b  ce call..**.** {
1c650 48 31 32 38 30 38 7d 20 43 61 6c 6c 73 20 74 6f  H12808} Calls to
1c660 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 74 68   API routines th
1c670 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 72 6e  at do not return
1c680 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a   an error code.*
1c690 2a 20 20 20 20 20 20 20 20 20 20 28 65 78 61 6d  *          (exam
1c6a0 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  ple: [sqlite3_da
1c6b0 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f 20  ta_count()]) do 
1c6c0 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  not.**          
1c6d0 63 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72  change the error
1c6e0 20 63 6f 64 65 20 6f 72 20 6d 65 73 73 61 67 65   code or message
1c6f0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1c700 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1c710 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73  3_errcode()], [s
1c720 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1c730 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  , or [sqlite3_er
1c740 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  rmsg16()]..**.**
1c750 20 7b 48 31 32 38 30 39 7d 20 49 6e 74 65 72 66   {H12809} Interf
1c760 61 63 65 73 20 74 68 61 74 20 61 72 65 20 6e 6f  aces that are no
1c770 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
1c780 68 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  h a specific.** 
1c790 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
1c7a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
1c7b0 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20 20  examples:.**    
1c7c0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d        [sqlite3_m
1c7d0 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71  printf()] or [sq
1c7e0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
1c7f0 72 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a 20  red_cache()].** 
1c800 20 20 20 20 20 20 20 20 20 64 6f 20 6e 6f 74 20           do not 
1c810 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
1c820 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
1c830 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1c840 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b  e3_errcode()], [
1c850 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1c860 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  ], or [sqlite3_e
1c870 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69  rrmsg16()]..*/.i
1c880 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
1c890 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
1c8a0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1c8b0 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
1c8c0 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
1c8d0 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
1c8e0 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  g16(sqlite3*);..
1c8f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c900 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
1c910 6a 65 63 74 20 7b 48 31 33 30 30 30 7d 20 3c 48  ject {H13000} <H
1c920 31 33 30 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  13010>.** KEYWOR
1c930 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
1c940 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
1c950 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
1c960 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
1c970 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
1c980 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
1c990 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
1c9a0 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
1c9b0 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b  t is variously k
1c9c0 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61  nown as a "prepa
1c9d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  red statement" o
1c9e0 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64  r a.** "compiled
1c9f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20   SQL statement" 
1ca00 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22  or simply as a "
1ca10 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a  statement"..**.*
1ca20 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20  * The life of a 
1ca30 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
1ca40 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20   goes something 
1ca50 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
1ca60 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
1ca70 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20  eate the object 
1ca80 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
1ca90 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1caa0 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20  a related.**    
1cab0 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c    function..** <
1cac0 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
1cad0 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74  to [host paramet
1cae0 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
1caf0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
1cb00 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
1cb10 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
1cb20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
1cb30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
1cb40 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
1cb50 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
1cb60 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65  eset the stateme
1cb70 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
1cb80 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
1cb90 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
1cba0 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
1cbb0 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
1cbc0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
1cbd0 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
1cbe0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
1cbf0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
1cc00 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65  * </ol>.**.** Re
1cc10 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61  fer to documenta
1cc20 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
1cc30 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  al methods above
1cc40 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
1cc50 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
1cc60 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
1cc70 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
1cc80 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
1cc90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
1cca0 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20 7b 48  n-time Limits {H
1ccb0 31 32 37 36 30 7d 20 3c 53 32 30 36 30 30 3e 0a  12760} <S20600>.
1ccc0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
1ccd0 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
1cce0 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
1ccf0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
1cd00 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
1cd10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
1cd20 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
1cd30 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
1cd40 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
1cd50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1cd60 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
1cd70 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
1cd80 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
1cd90 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
1cda0 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
1cdb0 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
1cdc0 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
1cdd0 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
1cde0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
1cdf0 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
1ce00 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
1ce10 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
1ce20 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
1ce30 63 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20  construct.  The 
1ce40 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1ce50 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a   the old limit..
1ce60 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65 77  **.** If the new
1ce70 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
1ce80 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
1ce90 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
1cea0 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20  ged..** For the 
1ceb0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f  limit category o
1cec0 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58  f SQLITE_LIMIT_X
1ced0 59 5a 20 74 68 65 72 65 20 69 73 20 61 20 68 61  YZ there is a ha
1cee0 72 64 20 75 70 70 65 72 0a 2a 2a 20 62 6f 75 6e  rd upper.** boun
1cef0 64 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69  d set by a compi
1cf00 6c 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f  le-time C prepro
1cf10 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d  cessor macro nam
1cf20 65 64 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59  ed SQLITE_MAX_XY
1cf30 5a 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  Z..** (The "_LIM
1cf40 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
1cf50 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
1cf60 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65  _MAX_".).** Atte
1cf70 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
1cf80 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
1cf90 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
1cfa0 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
1cfb0 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
1cfc0 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
1cfd0 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  limit..**.** Run
1cfe0 20 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65   time limits are
1cff0 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
1d000 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
1d010 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
1d020 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
1d030 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
1d040 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
1d050 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
1d060 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
1d070 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
1d080 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
1d090 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
1d0a0 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
1d0b0 20 77 65 62 62 72 6f 77 73 65 72 20 74 68 61 74   webbrowser that
1d0c0 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
1d0d0 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
1d0e0 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
1d0f0 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
1d100 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
1d110 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
1d120 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
1d130 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
1d140 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
1d150 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
1d160 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
1d170 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
1d180 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
1d190 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
1d1a0 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
1d1b0 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
1d1c0 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
1d1d0 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
1d1e0 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
1d1f0 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
1d200 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
1d210 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
1d220 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
1d230 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1d240 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
1d250 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
1d260 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
1d270 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
1d280 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
1d290 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
1d2a0 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
1d2b0 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
1d2c0 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
1d2d0 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
1d2e0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
1d2f0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
1d300 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
1d310 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
1d320 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
1d330 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  eases..**.** INV
1d340 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1d350 48 31 32 37 36 32 7d 20 41 20 73 75 63 63 65 73  H12762} A succes
1d360 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
1d370 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c  lite3_limit(D,C,
1d380 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 0a 2a  V)] where V is.*
1d390 2a 20 20 20 20 20 20 20 20 20 20 70 6f 73 69 74  *          posit
1d3a0 69 76 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ive changes the 
1d3b0 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a  limit on the siz
1d3c0 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43  e of construct C
1d3d0 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
1d3e0 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
1d3f0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 74  nnection] D to t
1d400 68 65 20 6c 65 73 73 65 72 20 6f 66 20 56 20 61  he lesser of V a
1d410 6e 64 20 74 68 65 20 68 61 72 64 20 75 70 70 65  nd the hard uppe
1d420 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6f  r.**          bo
1d430 75 6e 64 20 6f 6e 20 74 68 65 20 73 69 7a 65 20  und on the size 
1d440 6f 66 20 43 20 74 68 61 74 20 69 73 20 73 65 74  of C that is set
1d450 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1d460 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 36 7d  ..**.** {H12766}
1d470 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
1d480 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c  ll to [sqlite3_l
1d490 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65  imit(D,C,V)] whe
1d4a0 72 65 20 56 20 69 73 20 6e 65 67 61 74 69 76 65  re V is negative
1d4b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 65 61  .**          lea
1d4c0 76 65 73 20 74 68 65 20 73 74 61 74 65 20 6f 66  ves the state of
1d4d0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1d4e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 75 6e 63  onnection] D unc
1d4f0 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  hanged..**.** {H
1d500 31 32 37 36 39 7d 20 41 20 73 75 63 63 65 73 73  12769} A success
1d510 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
1d520 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56  ite3_limit(D,C,V
1d530 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  )] returns the.*
1d540 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
1d550 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e   of the limit on
1d560 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e   the size of con
1d570 73 74 72 75 63 74 20 43 20 69 6e 20 74 68 65 0a  struct C in the.
1d580 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
1d590 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d5a0 5d 20 44 20 61 73 20 69 74 20 77 61 73 20 70 72  ] D as it was pr
1d5b0 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e  ior to the call.
1d5c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1d5d0 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
1d5e0 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
1d5f0 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
1d600 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
1d610 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 20  imit Categories 
1d620 7b 48 31 32 37 39 30 7d 20 3c 48 31 32 37 36 30  {H12790} <H12760
1d630 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
1d640 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
1d650 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  {limit categorie
1d660 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
1d670 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
1d680 76 61 72 69 6f 75 73 20 61 73 70 65 63 74 73 20  various aspects 
1d690 6f 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  of a [database c
1d6a0 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68  onnection].** th
1d6b0 61 74 20 63 61 6e 20 62 65 20 6c 69 6d 69 74 65  at can be limite
1d6c0 64 20 69 6e 20 73 69 7a 65 20 62 79 20 63 61 6c  d in size by cal
1d6d0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c  ls to [sqlite3_l
1d6e0 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
1d6f0 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
1d700 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 61  various limits a
1d710 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  re as follows:.*
1d720 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
1d730 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
1d740 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1d750 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
1d760 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
1d770 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
1d780 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20   row.<dd>.**.** 
1d790 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1d7a0 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
1d7b0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1d7c0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
1d7d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c   SQL statement.<
1d7e0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1d7f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
1d800 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
1d810 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1d820 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
1d830 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
1d840 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
1d850 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
1d860 53 45 4c 45 43 54 20 6f 72 20 74 68 65 20 6d 61  SELECT or the ma
1d870 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1d880 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
1d890 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
1d8a0 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
1d8b0 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
1d8c0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1d8d0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
1d8e0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
1d8f0 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
1d900 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
1d910 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
1d920 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ssion.</dd>.**.*
1d930 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1d940 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
1d950 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
1d960 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1d970 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
1d980 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
1d990 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a  statement.</dd>.
1d9a0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1d9b0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
1d9c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1d9d0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1d9e0 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
1d9f0 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
1da00 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
1da10 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
1da20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1da30 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1da40 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
1da50 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
1da60 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1da70 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
1da80 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
1da90 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
1daa0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1dab0 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
1dac0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1dad0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 74 74  um number of att
1dae0 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 2e  ached databases.
1daf0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1db00 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
1db10 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
1db20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1db30 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
1db40 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
1db50 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 4c  rgument to the L
1db60 49 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f 42 20 6f  IKE or.** GLOB o
1db70 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a  perators.</dd>.*
1db80 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1db90 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
1dba0 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
1dbb0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1dbc0 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65  mber of variable
1dbd0 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  s in an SQL stat
1dbe0 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a  ement that can.*
1dbf0 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e  * be bound.</dd>
1dc00 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
1dc10 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1dc20 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  T_LENGTH        
1dc30 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
1dc40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1dc50 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20  IT_SQL_LENGTH   
1dc60 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
1dc70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1dc80 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20  MIT_COLUMN      
1dc90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
1dca0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1dcb0 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20  IMIT_EXPR_DEPTH 
1dcc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
1dcd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1dce0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
1dcf0 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
1dd00 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
1dd10 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20  _LIMIT_VDBE_OP  
1dd20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1dd30 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
1dd40 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
1dd50 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20  _ARG            
1dd60 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
1dd70 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
1dd80 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
1dd90 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
1dda0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
1ddb0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20  ATTERN_LENGTH   
1ddc0 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
1ddd0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
1dde0 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20  BLE_NUMBER      
1ddf0 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41       9../*.** CA
1de00 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e  PI3REF: Compilin
1de10 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  g An SQL Stateme
1de20 6e 74 20 7b 48 31 33 30 31 30 7d 20 3c 53 31 30  nt {H13010} <S10
1de30 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  000>.** KEYWORDS
1de40 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  : {SQL statement
1de50 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a   compiler}.**.**
1de60 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53   To execute an S
1de70 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73  QL query, it mus
1de80 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
1de90 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
1dea0 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
1deb0 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
1dec0 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
1ded0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
1dee0 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20  ument, "db", is 
1def0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
1df00 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64  ection] obtained
1df10 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72   from a.** prior
1df20 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1df30 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1df40 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
1df50 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
1df60 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  6()]..**.** The 
1df70 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
1df80 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20   "zSql", is the 
1df90 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
1dfa0 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
1dfb0 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
1dfc0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
1dfd0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
1dfe0 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
1dff0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a  e3_prepare_v2().
1e000 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
1e010 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c  e UTF-8, and sql
1e020 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1e030 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1e040 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75  pare16_v2().** u
1e050 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  se UTF-16..**.**
1e060 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72   If the nByte ar
1e070 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74  gument is less t
1e080 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a  han zero, then z
1e090 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
1e0a0 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a  o the.** first z
1e0b0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1e0c0 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  If nByte is non-
1e0d0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
1e0e0 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  t is the maximum
1e0f0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62  .** number of  b
1e100 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
1e110 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65  Sql.  When nByte
1e120 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
1e130 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74  , the.** zSql st
1e140 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74  ring ends at eit
1e150 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c  her the first '\
1e160 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27  000' or '\u0000'
1e170 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a   character or.**
1e180 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79   the nByte-th by
1e190 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  te, whichever co
1e1a0 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68  mes first. If th
1e1b0 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a  e caller knows.*
1e1c0 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  * that the suppl
1e1d0 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
1e1e0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
1e1f0 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  en there is a sm
1e200 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e  all.** performan
1e210 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
1e220 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73  be gained by pas
1e230 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
1e240 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
1e250 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  is equal to the 
1e260 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1e270 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
1e280 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
1e290 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
1e2a0 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73  terminator bytes
1e2b0 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20  ..**.** *pzTail 
1e2c0 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
1e2d0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
1e2e0 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  te past the end 
1e2f0 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
1e300 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1e310 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
1e320 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d 70  utines only comp
1e330 69 6c 65 20 74 68 65 20 66 69 72 73 74 0a 2a 2a  ile the first.**
1e340 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
1e350 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
1e360 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
1e370 74 6f 20 77 68 61 74 20 72 65 6d 61 69 6e 73 0a  to what remains.
1e380 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ** uncompiled..*
1e390 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20  *.** *ppStmt is 
1e3a0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
1e3b0 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
1e3c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e3d0 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
1e3e0 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
1e3f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1e400 20 20 49 66 20 74 68 65 72 65 20 69 73 20 61 6e    If there is an
1e410 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
1e420 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
1e430 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75 74  L.  If the input
1e440 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
1e450 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
1e460 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
1e470 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
1e480 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
1e490 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
1e4a0 55 4c 4c 2e 0a 2a 2a 20 7b 41 31 33 30 31 38 7d  ULL..** {A13018}
1e4b0 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
1e4c0 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
1e4d0 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
1e4e0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
1e4f0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1e500 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1e510 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
1e520 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
1e530 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a  d with it..**.**
1e540 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51   On success, [SQ
1e550 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
1e560 72 6e 65 64 2c 20 6f 74 68 65 72 77 69 73 65 20  rned, otherwise 
1e570 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
1e580 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1e590 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
1e5a0 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
1e5b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1e5c0 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
1e5d0 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
1e5e0 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
1e5f0 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
1e600 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
1e610 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
1e620 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
1e630 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
1e640 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
1e650 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
1e660 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e  * In the "v2" in
1e670 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
1e680 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1e690 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
1e6a0 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
1e6b0 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
1e6c0 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
1e6d0 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
1e6e0 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
1e6f0 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
1e700 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
1e710 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
1e720 65 68 61 76 65 20 61 20 64 69 66 66 65 72 65 6e  ehave a differen
1e730 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73 3a  tly in two ways:
1e740 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
1e750 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  li>.** If the da
1e760 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
1e770 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
1e780 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
1e790 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
1e7a0 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
1e7b0 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
1e7c0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
1e7d0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
1e7e0 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
1e7f0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
1e800 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
1e810 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68 65  in.  If the sche
1e820 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69  ma has changed i
1e830 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20  n.** a way that 
1e840 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d  makes the statem
1e850 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61  ent no longer va
1e860 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  lid, [sqlite3_st
1e870 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c  ep()] will still
1e880 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
1e890 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74  TE_SCHEMA].  But
1e8a0 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61   unlike the lega
1e8b0 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51  cy behavior, [SQ
1e8c0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a  LITE_SCHEMA] is.
1e8d0 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65  ** now a fatal e
1e8e0 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b  rror.  Calling [
1e8f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1e900 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c  v2()] again will
1e910 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a   not make the.**
1e920 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20   error go away. 
1e930 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69   Note: use [sqli
1e940 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f  te3_errmsg()] to
1e950 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a   find the text.*
1e960 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67  * of the parsing
1e970 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 73 75   error that resu
1e980 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  lts in an [SQLIT
1e990 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e  E_SCHEMA] return
1e9a0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
1e9b0 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e   <li>.** When an
1e9c0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
1e9d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1e9e0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
1e9f0 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
1ea00 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
1ea10 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
1ea20 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 54 68 65  ror codes].  The
1ea30 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
1ea40 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
1ea50 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
1ea60 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
1ea70 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
1ea80 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
1ea90 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79 6f 75 20  code.** and you 
1eaa0 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
1eab0 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
1eac0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
1ead0 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 0a 2a  et()] in order.*
1eae0 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  * to find the un
1eaf0 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
1eb00 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
1eb10 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
1eb20 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
1eb30 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
1eb40 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
1eb50 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
1eb60 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
1eb70 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
1eb80 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  l>.**.** INVARIA
1eb90 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30  NTS:.**.** {H130
1eba0 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  11} The [sqlite3
1ebb0 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c  _prepare(db,zSql
1ebc0 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  ,...)] and.**   
1ebd0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1ebe0 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53  prepare_v2(db,zS
1ebf0 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ql,...)] interfa
1ec00 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 74 68  ces interpret th
1ec10 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65  e.**          te
1ec20 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c  xt in their zSql
1ec30 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 55 54   parameter as UT
1ec40 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30  F-8..**.** {H130
1ec50 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  12} The [sqlite3
1ec60 5f 70 72 65 70 61 72 65 31 36 28 64 62 2c 7a 53  _prepare16(db,zS
1ec70 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20  ql,...)] and.** 
1ec80 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1ec90 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 64  3_prepare16_v2(d
1eca0 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74  b,zSql,...)] int
1ecb0 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72 65  erfaces interpre
1ecc0 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  t the.**        
1ecd0 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72 20    text in their 
1ece0 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61  zSql parameter a
1ecf0 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
1ed00 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1ed10 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 33  r..**.** {H13013
1ed20 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61  } If the nByte a
1ed30 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
1ed40 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64  te3_prepare_v2(d
1ed50 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e  b,zSql,nByte,...
1ed60 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
1ed70 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  nd its variants 
1ed80 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
1ed90 6f 2c 20 74 68 65 20 53 51 4c 20 74 65 78 74 20  o, the SQL text 
1eda0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  is.**          r
1edb0 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 20 69 73  ead from zSql is
1edc0 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 20   read up to the 
1edd0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
1ede0 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  nator..**.** {H1
1edf0 33 30 31 34 7d 20 49 66 20 74 68 65 20 6e 42 79  3014} If the nBy
1ee00 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  te argument to [
1ee10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1ee20 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65  v2(db,zSql,nByte
1ee30 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
1ee40 20 20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61     and its varia
1ee50 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  nts is non-negat
1ee60 69 76 65 2c 20 74 68 65 6e 20 61 74 20 6d 6f 73  ive, then at mos
1ee70 74 20 6e 42 79 74 65 73 20 62 79 74 65 73 20 6f  t nBytes bytes o
1ee80 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  f.**          SQ
1ee90 4c 20 74 65 78 74 20 69 73 20 72 65 61 64 20 66  L text is read f
1eea0 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20  rom zSql..**.** 
1eeb0 7b 48 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c  {H13015} In [sql
1eec0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1eed0 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61  db,zSql,N,P,pzTa
1eee0 69 6c 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  il)] and its var
1eef0 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  iants.**        
1ef00 20 20 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e    if the zSql in
1ef10 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
1ef20 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
1ef30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
1ef40 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a            and pz
1ef50 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
1ef60 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  , then *pzTail i
1ef70 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
1ef80 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
1ef90 20 20 20 66 69 72 73 74 20 62 79 74 65 20 70 61     first byte pa
1efa0 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
1efb0 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
1efc0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a  ement in zSql..*
1efd0 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f  *          <todo
1efe0 3e 57 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61  >What does *pzTa
1eff0 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74  il point to if t
1f000 68 65 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74  here is one stat
1f010 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a  ement?</todo>.**
1f020 0a 2a 2a 20 7b 48 31 33 30 31 36 7d 20 41 20 73  .** {H13016} A s
1f030 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
1f040 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
1f050 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c  re_v2(db,zSql,N,
1f060 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20  ppStmt,...)].** 
1f070 20 20 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20           or one 
1f080 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  of its variants 
1f090 77 72 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53  writes into *ppS
1f0a0 74 6d 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  tmt a pointer to
1f0b0 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20   a new.**       
1f0c0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
1f0d0 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69  tement] or a poi
1f0e0 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 69 66 20  nter to NULL if 
1f0f0 7a 53 71 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  zSql contains.**
1f100 20 20 20 20 20 20 20 20 20 20 6e 6f 74 68 69 6e            nothin
1f110 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69  g other than whi
1f120 74 65 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65  tespace or comme
1f130 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30  nts..**.** {H130
1f140 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  19} The [sqlite3
1f150 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
1f160 6e 74 65 72 66 61 63 65 20 61 6e 64 20 69 74 73  nterface and its
1f170 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e   variants return
1f180 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
1f190 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61  LITE_OK] or an a
1f1a0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
1f1b0 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69  r code] upon fai
1f1c0 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  lure..**.** {H13
1f1d0 30 32 31 7d 20 42 65 66 6f 72 65 20 5b 73 71 6c  021} Before [sql
1f1e0 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c  ite3_prepare(db,
1f1f0 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53 74 6d  zSql,nByte,ppStm
1f200 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20 69 74  t,pzTail)] or it
1f210 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  s.**          va
1f220 72 69 61 6e 74 73 20 72 65 74 75 72 6e 73 20 61  riants returns a
1f230 6e 20 65 72 72 6f 72 20 28 61 6e 79 20 76 61 6c  n error (any val
1f240 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
1f250 51 4c 49 54 45 5f 4f 4b 5d 29 2c 0a 2a 2a 20 20  QLITE_OK]),.**  
1f260 20 20 20 20 20 20 20 20 74 68 65 79 20 66 69 72          they fir
1f270 73 74 20 73 65 74 20 2a 70 70 53 74 6d 74 20 74  st set *ppStmt t
1f280 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
1f290 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
1f2a0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1f2b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1f2c0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1f2d0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1f2e0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1f2f0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1f300 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
1f310 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1f320 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1f330 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1f340 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1f350 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1f360 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1f370 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1f380 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1f390 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1f3a0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1f3b0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1f3c0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
1f3d0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1f3e0 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
1f3f0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1f400 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1f410 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1f420 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
1f430 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1f440 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
1f450 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1f460 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1f470 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1f480 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1f490 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1f4a0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1f4b0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1f4c0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1f4d0 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
1f4e0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1f4f0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1f500 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1f510 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1f520 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
1f530 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1f540 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
1f550 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1f560 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
1f570 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
1f580 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
1f590 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1f5a0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1f5b0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1f5c0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1f5d0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1f5e0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1f5f0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1f600 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1f610 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
1f620 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1f630 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1f640 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1f650 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
1f660 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1f670 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
1f680 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1f690 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1f6a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1f6b0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1f6c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1f6d0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
1f6e0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1f6f0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1f700 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1f710 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1f720 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1f730 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1f740 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1f750 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1f760 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
1f770 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1f780 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1f790 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1f7a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45  );../*.** CAPIRE
1f7b0 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
1f7c0 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 48 31 33  atement SQL {H13
1f7d0 31 30 30 7d 20 3c 48 31 33 30 30 30 3e 0a 2a 2a  100} <H13000>.**
1f7e0 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1f7f0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
1f800 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76  o retrieve a sav
1f810 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f  ed copy of the o
1f820 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74  riginal.** SQL t
1f830 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
1f840 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
1f850 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61  tatement] if tha
1f860 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a  t statement was.
1f870 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e  ** compiled usin
1f880 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
1f890 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1f8a0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
1f8b0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
1f8c0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1f8d0 2a 0a 2a 2a 20 7b 48 31 33 31 30 31 7d 20 49 66  *.** {H13101} If
1f8e0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1f8f0 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64  tatement] passed
1f900 20 61 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   as the argument
1f910 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
1f920 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20  [sqlite3_sql()] 
1f930 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  was compiled usi
1f940 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
1f950 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1f960 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
1f970 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f980 31 36 5f 76 32 28 29 5d 2c 20 74 68 65 6e 20 5b  16_v2()], then [
1f990 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 72  sqlite3_sql()] r
1f9a0 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
1f9b0 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20     a pointer to 
1f9c0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1f9d0 64 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  d string contain
1f9e0 69 6e 67 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ing a UTF-8 rend
1f9f0 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  ering.**        
1fa00 20 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61    of the origina
1fa10 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  l SQL statement.
1fa20 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 32 7d 20  .**.** {H13102} 
1fa30 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  If the [prepared
1fa40 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 73   statement] pass
1fa50 65 64 20 61 73 20 74 68 65 20 61 72 67 75 6d 65  ed as the argume
1fa60 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  nt to.**        
1fa70 20 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29    [sqlite3_sql()
1fa80 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 75  ] was compiled u
1fa90 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
1faa0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1fab0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
1fac0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1fad0 36 28 29 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69  6()], then [sqli
1fae0 74 65 33 5f 73 71 6c 28 29 5d 20 72 65 74 75 72  te3_sql()] retur
1faf0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
1fb00 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 33  r..**.** {H13103
1fb10 7d 20 54 68 65 20 73 74 72 69 6e 67 20 72 65 74  } The string ret
1fb20 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1fb30 33 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61 6c  3_sql(S)] is val
1fb40 69 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a 20  id until the.** 
1fb50 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
1fb60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1fb70 69 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67  is deleted using
1fb80 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1fb90 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  ze(S)]..*/.const
1fba0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1fbb0 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
1fbc0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
1fbd0 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
1fbe0 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
1fbf0 65 20 4f 62 6a 65 63 74 20 7b 48 31 35 30 30 30  e Object {H15000
1fc00 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45  } <S20200>.** KE
1fc10 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
1fc20 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1fc30 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
1fc40 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
1fc50 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
1fc60 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
1fc70 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
1fc80 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
1fc90 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
1fca0 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
1fcb0 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
1fcc0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
1fcd0 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
1fce0 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
1fcf0 65 73 2e 20 56 61 6c 75 65 73 20 73 74 6f 72 65  es. Values store
1fd00 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
1fd10 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
1fd20 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
1fd30 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
1fd40 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
1fd50 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
1fd60 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
1fd70 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
1fd80 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
1fd90 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
1fda0 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
1fdb0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
1fdc0 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
1fdd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
1fde0 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
1fdf0 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
1fe00 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
1fe10 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
1fe20 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1fe30 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
1fe40 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
1fe50 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
1fe60 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
1fe70 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
1fe80 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
1fe90 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
1fea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
1feb0 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
1fec0 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
1fed0 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
1fee0 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
1fef0 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
1ff00 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65  is held.  A inte
1ff10 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
1ff20 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
1ff30 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1ff40 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
1ff50 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
1ff60 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
1ff70 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1ff80 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
1ff90 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
1ffa0 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
1ffb0 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
1ffc0 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
1ffd0 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
1ffe0 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
1fff0 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
20000 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
20010 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
20020 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
20030 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
20040 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
20050 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
20060 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
20070 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
20080 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
20090 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
200a0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
200b0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
200c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
200d0 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
200e0 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
200f0 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
20100 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
20110 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
20120 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
20130 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
20140 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
20150 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
20160 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 62  nction between b
20170 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
20180 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
20190 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
201a0 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
201b0 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
201c0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
201d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
201e0 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
201f0 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
20200 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
20210 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
20220 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
20230 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
20240 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
20250 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 54 68 65  rotected..** The
20260 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
20270 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
20280 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
20290 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
202a0 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a   unprotected..**
202b0 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   Unprotected sql
202c0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
202d0 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ts may only be u
202e0 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  sed with.** [sql
202f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
20300 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
20310 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e  3_bind_value()].
20320 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
20330 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
20340 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
20350 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
20360 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
20370 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
20380 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
20390 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
203a0 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
203b0 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
203c0 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46   CAPI3REF: SQL F
203d0 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
203e0 4f 62 6a 65 63 74 20 7b 48 31 36 30 30 31 7d 20  Object {H16001} 
203f0 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20200>.**.** T
20400 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
20410 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
20420 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
20430 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
20440 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
20450 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74  object.  A point
20460 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
20470 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
20480 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
20490 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
204a0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
204b0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
204c0 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
204d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
204e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
204f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
20500 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
20510 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
20520 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
20530 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
20540 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
20550 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
20560 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
20570 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
20580 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
20590 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
205a0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
205b0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
205c0 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
205d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
205e0 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
205f0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
20600 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
20610 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
20620 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20630 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
20640 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
20650 6d 65 6e 74 73 20 7b 48 31 33 35 30 30 7d 20 3c  ments {H13500} <
20660 53 37 30 33 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S70300>.** KEYWO
20670 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
20680 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
20690 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
206a0 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
206b0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
206c0 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
206d0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
206e0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
206f0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c  **.** In the SQL
20700 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74   strings input t
20710 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
20720 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
20730 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
20740 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
20750 70 6c 61 63 65 64 20 62 79 20 61 20 70 61 72 61  placed by a para
20760 6d 65 74 65 72 20 69 6e 20 6f 6e 65 20 6f 66 20  meter in one of 
20770 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a  these forms:.**.
20780 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
20790 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
207a0 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
207b0 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
207c0 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
207d0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
207e0 20 70 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73   parameter forms
207f0 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e   shown above NNN
20800 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c   is an integer l
20810 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56  iteral,.** and V
20820 56 56 20 69 73 20 61 6e 20 61 6c 70 68 61 2d 6e  VV is an alpha-n
20830 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74 65 72  umeric parameter
20840 20 6e 61 6d 65 2e 20 54 68 65 20 76 61 6c 75 65   name. The value
20850 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
20860 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
20870 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
20880 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
20890 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
208a0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
208b0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
208c0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
208d0 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
208e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
208f0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
20900 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
20910 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
20920 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
20930 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
20940 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
20950 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
20960 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20970 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
20980 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  ariants..**.** T
20990 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
209a0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
209b0 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
209c0 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
209d0 2a 2a 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  ** The leftmost 
209e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
209f0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
20a00 20 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20    When the same 
20a10 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
20a20 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
20a30 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
20a40 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
20a50 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
20a60 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
20a70 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
20a80 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
20a90 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20 66 6f  .** The index fo
20aa0 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
20ab0 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
20ac0 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
20ad0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
20ae0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
20af0 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
20b00 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20  .  The index.** 
20b10 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
20b20 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
20b30 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68  ue of NNN..** Th
20b40 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74  e NNN value must
20b50 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e   be between 1 an
20b60 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  d the [sqlite3_l
20b70 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d  imit()].** param
20b80 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d  eter [SQLITE_LIM
20b90 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
20ba0 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c  ER] (default val
20bb0 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20  ue: 999)..**.** 
20bc0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
20bd0 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
20be0 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
20bf0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
20c00 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
20c10 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
20c20 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
20c30 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
20c40 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
20c50 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
20c60 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
20c70 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
20c80 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
20c90 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
20ca0 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
20cb0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
20cc0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66 20  aracters..** If 
20cd0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
20ce0 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
20cf0 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  , the length of 
20d00 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
20d10 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
20d20 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
20d30 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
20d40 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ator..**.** The 
20d50 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
20d60 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
20d70 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62  lob(), sqlite3_b
20d80 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a  ind_text(), and.
20d90 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
20da0 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65  text16() is a de
20db0 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
20dc0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
20dd0 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e  BLOB or.** strin
20de0 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68  g after SQLite h
20df0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
20e00 20 69 74 2e 20 49 66 20 74 68 65 20 66 69 66 74   it. If the fift
20e10 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
20e20 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
20e30 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
20e40 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
20e50 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
20e60 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
20e70 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
20e80 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
20e90 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
20ea0 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
20eb0 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
20ec0 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61  ument has the va
20ed0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  lue [SQLITE_TRAN
20ee0 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20  SIENT], then.** 
20ef0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
20f00 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
20f10 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d  y of the data im
20f20 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
20f30 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  e.** the sqlite3
20f40 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
20f50 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  e returns..**.**
20f60 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   The sqlite3_bin
20f70 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
20f80 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
20f90 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
20fa0 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
20fb0 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 41 20  with zeroes.  A 
20fc0 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
20fd0 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
20fe0 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
20ff0 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
21000 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
21010 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
21020 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
21030 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
21040 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
21050 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
21060 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
21070 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
21080 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
21090 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
210a0 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
210b0 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
210c0 74 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67 61  tines..** A nega
210d0 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
210e0 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
210f0 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
21100 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
21110 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   The sqlite3_bin
21120 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d  d_*() routines m
21130 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66  ust be called af
21140 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ter.** [sqlite3_
21150 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61  prepare_v2()] (a
21160 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  nd its variants)
21170 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
21180 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66  et()] and.** bef
21190 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ore [sqlite3_ste
211a0 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67  p()]..** Binding
211b0 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
211c0 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
211d0 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
211e0 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70  ne..** Unbound p
211f0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
21200 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
21210 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  L..**.** These r
21220 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
21230 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
21240 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f  ccess or an erro
21250 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79  r code if.** any
21260 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
21270 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  .  [SQLITE_RANGE
21280 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
21290 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
212a0 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
212b0 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54  f range.  [SQLIT
212c0 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
212d0 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
212e0 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49   fails..** [SQLI
212f0 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74  TE_MISUSE] might
21300 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20   be returned if 
21310 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
21320 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a  re called on a.*
21330 2a 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  * virtual machin
21340 65 20 74 68 61 74 20 69 73 20 74 68 65 20 77 72  e that is the wr
21350 6f 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68 69  ong state or whi
21360 63 68 20 68 61 73 20 61 6c 72 65 61 64 79 20 62  ch has already b
21370 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a  een finalized..*
21380 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d  * Detection of m
21390 69 73 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61  isuse is unrelia
213a0 62 6c 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ble.  Applicatio
213b0 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65  ns should not de
213c0 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54  pend.** on SQLIT
213d0 45 5f 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73  E_MISUSE returns
213e0 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  .  SQLITE_MISUSE
213f0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
21400 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20  indicate a.** a 
21410 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74  logic error in t
21420 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
21430 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
21440 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
21450 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72  .** panic rather
21460 20 74 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c   than return SQL
21470 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a  ITE_MISUSE..**.*
21480 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
21490 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
214a0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
214b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
214c0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
214d0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
214e0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
214f0 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  dex()]..**.** IN
21500 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
21510 7b 48 31 33 35 30 36 7d 20 54 68 65 20 5b 53 51  {H13506} The [SQ
21520 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
21530 69 6c 65 72 5d 20 72 65 63 6f 67 6e 69 7a 65 73  iler] recognizes
21540 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20 66   tokens of the f
21550 6f 72 6d 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  orms.**         
21560 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24   "?", "?NNN", "$
21570 56 56 56 22 2c 20 22 3a 56 56 56 22 2c 20 61 6e  VVV", ":VVV", an
21580 64 20 22 40 56 56 56 22 20 61 73 20 53 51 4c 20  d "@VVV" as SQL 
21590 70 61 72 61 6d 65 74 65 72 73 2c 0a 2a 2a 20 20  parameters,.**  
215a0 20 20 20 20 20 20 20 20 77 68 65 72 65 20 4e 4e          where NN
215b0 4e 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63  N is any sequenc
215c0 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  e of one or more
215d0 20 64 69 67 69 74 73 0a 2a 2a 20 20 20 20 20 20   digits.**      
215e0 20 20 20 20 61 6e 64 20 77 68 65 72 65 20 56 56      and where VV
215f0 56 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63  V is any sequenc
21600 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  e of one or more
21610 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 0a 2a 2a   alphanumeric.**
21620 20 20 20 20 20 20 20 20 20 20 63 68 61 72 61 63            charac
21630 74 65 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70 74  ters or "::" opt
21640 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64  ionally followed
21650 20 62 79 20 61 20 73 74 72 69 6e 67 20 63 6f 6e   by a string con
21660 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20  taining.**      
21670 20 20 20 20 6e 6f 20 73 70 61 63 65 73 20 61 6e      no spaces an
21680 64 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68  d contained with
21690 69 6e 20 70 61 72 65 6e 74 68 65 73 65 73 2e 0a  in parentheses..
216a0 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 39 7d 20 54  **.** {H13509} T
216b0 68 65 20 69 6e 69 74 69 61 6c 20 76 61 6c 75 65  he initial value
216c0 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
216d0 65 74 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  eter is NULL..**
216e0 0a 2a 2a 20 7b 48 31 33 35 31 32 7d 20 54 68 65  .** {H13512} The
216f0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 22   index of an "?"
21700 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
21710 73 20 6f 6e 65 20 6c 61 72 67 65 72 20 74 68 61  s one larger tha
21720 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
21730 20 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20    largest index 
21740 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  of SQL parameter
21750 20 74 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f 72   to the left, or
21760 20 31 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20   1 if.**        
21770 20 20 74 68 65 20 22 3f 22 20 69 73 20 74 68 65    the "?" is the
21780 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
21790 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
217a0 48 31 33 35 31 35 7d 20 54 68 65 20 69 6e 64 65  H13515} The inde
217b0 78 20 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22 20 53  x of an "?NNN" S
217c0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
217d0 74 68 65 20 69 6e 74 65 67 65 72 20 4e 4e 4e 2e  the integer NNN.
217e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 38 7d 20  .**.** {H13518} 
217f0 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  The index of an 
21800 22 3a 56 56 56 22 2c 20 22 24 56 56 56 22 2c 20  ":VVV", "$VVV", 
21810 6f 72 20 22 40 56 56 56 22 20 53 51 4c 20 70 61  or "@VVV" SQL pa
21820 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20  rameter is.**   
21830 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20         the same 
21840 61 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  as the index of 
21850 6c 65 66 74 6d 6f 73 74 20 6f 63 63 75 72 72 65  leftmost occurre
21860 6e 63 65 73 20 6f 66 20 74 68 65 20 73 61 6d 65  nces of the same
21870 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
21880 61 6d 65 74 65 72 2c 20 6f 72 20 6f 6e 65 20 6d  ameter, or one m
21890 6f 72 65 20 74 68 61 6e 20 74 68 65 20 6c 61 72  ore than the lar
218a0 67 65 73 74 20 69 6e 64 65 78 20 6f 76 65 72 20  gest index over 
218b0 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
218c0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
218d0 65 20 6c 65 66 74 20 69 66 20 74 68 69 73 20 69  e left if this i
218e0 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
218f0 72 72 65 6e 63 65 0a 2a 2a 20 20 20 20 20 20 20  rrence.**       
21900 20 20 20 6f 66 20 74 68 69 73 20 70 61 72 61 6d     of this param
21910 65 74 65 72 2c 20 6f 72 20 31 20 69 66 20 74 68  eter, or 1 if th
21920 69 73 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f  is is the leftmo
21930 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
21940 0a 2a 2a 20 7b 48 31 33 35 32 31 7d 20 54 68 65  .** {H13521} The
21950 20 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   [SQL statement 
21960 63 6f 6d 70 69 6c 65 72 5d 20 66 61 69 6c 73 20  compiler] fails 
21970 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f  with an [SQLITE_
21980 52 41 4e 47 45 5d 0a 2a 2a 20 20 20 20 20 20 20  RANGE].**       
21990 20 20 20 65 72 72 6f 72 20 69 66 20 74 68 65 20     error if the 
219a0 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
219b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
219c0 73 20 74 68 61 6e 20 31 0a 2a 2a 20 20 20 20 20  s than 1.**     
219d0 20 20 20 20 20 6f 72 20 67 72 65 61 74 65 72 20       or greater 
219e0 74 68 61 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  than the compile
219f0 2d 74 69 6d 65 20 53 51 4c 49 54 45 5f 4d 41 58  -time SQLITE_MAX
21a00 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
21a10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
21a20 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ameter..**.** {H
21a30 31 33 35 32 34 7d 20 43 61 6c 6c 73 20 74 6f 20  13524} Calls to 
21a40 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
21a50 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  xt | sqlite3_bin
21a60 64 28 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a  d(S,N,V,...)].**
21a70 20 20 20 20 20 20 20 20 20 20 61 73 73 6f 63 69            associ
21a80 61 74 65 20 74 68 65 20 76 61 6c 75 65 20 56 20  ate the value V 
21a90 77 69 74 68 20 61 6c 6c 20 53 51 4c 20 70 61 72  with all SQL par
21aa0 61 6d 65 74 65 72 73 20 68 61 76 69 6e 67 20 61  ameters having a
21ab0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  n.**          in
21ac0 64 65 78 20 6f 66 20 4e 20 69 6e 20 74 68 65 20  dex of N in the 
21ad0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21ae0 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ent] S..**.** {H
21af0 31 33 35 32 37 7d 20 43 61 6c 6c 73 20 74 6f 20  13527} Calls to 
21b00 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
21b10 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  xt | sqlite3_bin
21b20 64 28 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  d(S,N,...)].**  
21b30 20 20 20 20 20 20 20 20 6f 76 65 72 72 69 64 65          override
21b40 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74   prior calls wit
21b50 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  h the same value
21b60 73 20 6f 66 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a  s of S and N..**
21b70 0a 2a 2a 20 7b 48 31 33 35 33 30 7d 20 42 69 6e  .** {H13530} Bin
21b80 64 69 6e 67 73 20 65 73 74 61 62 6c 69 73 68 65  dings establishe
21b90 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 69  d by [sqlite3_bi
21ba0 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
21bb0 33 5f 62 69 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a  3_bind(S,...)].*
21bc0 2a 20 20 20 20 20 20 20 20 20 20 70 65 72 73 69  *          persi
21bd0 73 74 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20  st across calls 
21be0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
21bf0 74 28 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  t(S)]..**.** {H1
21c00 33 35 33 33 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3533} In calls t
21c10 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
21c20 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  blob(S,N,V,L,D)]
21c30 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
21c40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
21c50 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72  (S,N,V,L,D)], or
21c60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
21c70 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
21c80 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51  6(S,N,V,L,D)] SQ
21c90 4c 69 74 65 20 62 69 6e 64 73 20 74 68 65 20 66  Lite binds the f
21ca0 69 72 73 74 20 4c 0a 2a 2a 20 20 20 20 20 20 20  irst L.**       
21cb0 20 20 20 62 79 74 65 73 20 6f 66 20 74 68 65 20     bytes of the 
21cc0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 70  BLOB or string p
21cd0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2c 20  ointed to by V, 
21ce0 77 68 65 6e 20 4c 0a 2a 2a 20 20 20 20 20 20 20  when L.**       
21cf0 20 20 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69     is non-negati
21d00 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33  ve..**.** {H1353
21d10 36 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  6} In calls to [
21d20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
21d30 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72  t(S,N,V,L,D)] or
21d40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
21d50 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
21d60 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51  6(S,N,V,L,D)] SQ
21d70 4c 69 74 65 20 62 69 6e 64 73 20 63 68 61 72 61  Lite binds chara
21d80 63 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  cters.**        
21d90 20 20 66 72 6f 6d 20 56 20 74 68 72 6f 75 67 68    from V through
21da0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
21db0 63 68 61 72 61 63 74 65 72 20 77 68 65 6e 20 4c  character when L
21dc0 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a   is negative..**
21dd0 0a 2a 2a 20 7b 48 31 33 35 33 39 7d 20 49 6e 20  .** {H13539} In 
21de0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
21df0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c  3_bind_blob(S,N,
21e00 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,L,D)],.**     
21e10 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
21e20 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c  nd_text(S,N,V,L,
21e30 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
21e40 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
21e50 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
21e60 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74  ,D)] when D is t
21e70 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20  he special.**   
21e80 20 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20         constant 
21e90 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
21ea0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
21eb0 74 68 61 74 20 74 68 65 20 76 61 6c 75 65 20 56  that the value V
21ec0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
21ed0 68 65 6c 64 20 69 6e 20 73 74 61 74 69 63 20 75  held in static u
21ee0 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 74  nmanaged space t
21ef0 68 61 74 20 77 69 6c 6c 20 6e 6f 74 20 63 68 61  hat will not cha
21f00 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nge.**          
21f10 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
21f20 69 6d 65 20 6f 66 20 74 68 65 20 62 69 6e 64 69  ime of the bindi
21f30 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34  ng..**.** {H1354
21f40 32 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  2} In calls to [
21f50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
21f60 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a  b(S,N,V,L,D)],.*
21f70 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
21f80 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c  te3_bind_text(S,
21f90 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  N,V,L,D)], or.**
21fa0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
21fb0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53  e3_bind_text16(S
21fc0 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20  ,N,V,L,D)] when 
21fd0 44 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  D is the special
21fe0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
21ff0 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 54 52  stant [SQLITE_TR
22000 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 20 72 6f  ANSIENT], the ro
22010 75 74 69 6e 65 20 6d 61 6b 65 73 20 61 0a 2a 2a  utine makes a.**
22020 20 20 20 20 20 20 20 20 20 20 70 72 69 76 61 74            privat
22030 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 61  e copy of the va
22040 6c 75 65 20 56 20 62 65 66 6f 72 65 20 69 74 20  lue V before it 
22050 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b  returns..**.** {
22060 48 31 33 35 34 35 7d 20 49 6e 20 63 61 6c 6c 73  H13545} In calls
22070 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
22080 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44  d_blob(S,N,V,L,D
22090 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
220a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
220b0 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20  xt(S,N,V,L,D)], 
220c0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
220d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
220e0 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20  t16(S,N,V,L,D)] 
220f0 77 68 65 6e 20 44 20 69 73 20 61 20 70 6f 69 6e  when D is a poin
22100 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ter to.**       
22110 20 20 20 61 20 66 75 6e 63 74 69 6f 6e 2c 20 53     a function, S
22120 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
22130 61 74 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 64  at function to d
22140 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20 20 20  estroy the.**   
22150 20 20 20 20 20 20 20 76 61 6c 75 65 20 56 20 61         value V a
22160 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
22170 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20 76  shed using the v
22180 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48  alue V..**.** {H
22190 31 33 35 34 38 7d 20 49 6e 20 63 61 6c 6c 73 20  13548} In calls 
221a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
221b0 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  _zeroblob(S,N,V,
221c0 4c 29 5d 20 74 68 65 20 76 61 6c 75 65 20 62 6f  L)] the value bo
221d0 75 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  und.**          
221e0 69 73 20 61 20 42 4c 4f 42 20 6f 66 20 4c 20 62  is a BLOB of L b
221f0 79 74 65 73 2c 20 6f 72 20 61 20 7a 65 72 6f 2d  ytes, or a zero-
22200 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 66 20 4c  length BLOB if L
22210 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a   is negative..**
22220 0a 2a 2a 20 7b 48 31 33 35 35 31 7d 20 49 6e 20  .** {H13551} In 
22230 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
22240 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 53 2c 4e  3_bind_value(S,N
22250 2c 56 29 5d 20 74 68 65 20 56 20 61 72 67 75 6d  ,V)] the V argum
22260 65 6e 74 20 6d 61 79 0a 2a 2a 20 20 20 20 20 20  ent may.**      
22270 20 20 20 20 62 65 20 65 69 74 68 65 72 20 61 20      be either a 
22280 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
22290 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
222a0 20 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20   or an.**       
222b0 20 20 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20     [unprotected 
222c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
222d0 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  bject..*/.int sq
222e0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
222f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
22300 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
22310 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
22320 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
22330 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
22340 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
22350 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e  int, double);.in
22360 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
22370 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
22380 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74  , int, int);.int
22390 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
223a0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
223b0 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
223c0 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69  int64);.int sqli
223d0 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
223e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
223f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
22400 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
22410 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
22420 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c  st char*, int n,
22430 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
22440 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
22450 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
22460 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
22470 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
22480 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
22490 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
224a0 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
224b0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
224c0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
224d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
224e0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
224f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
22500 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
22510 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
22520 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
22530 72 73 20 7b 48 31 33 36 30 30 7d 20 3c 53 37 30  rs {H13600} <S70
22540 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  300>.**.** This 
22550 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
22560 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
22570 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
22580 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
22590 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
225a0 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
225b0 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
225c0 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
225d0 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
225e0 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
225f0 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
22600 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
22610 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
22620 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
22630 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
22640 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
22650 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
22660 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
22670 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
22680 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
22690 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
226a0 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
226b0 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
226c0 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
226d0 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
226e0 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
226f0 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
22700 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
22710 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
22720 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
22730 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c  e ?NNN are used,
22740 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
22750 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
22760 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  t..**.** See als
22770 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
22780 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
22790 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
227a0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
227b0 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
227c0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
227d0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
227e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
227f0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
22800 36 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  601} The [sqlite
22810 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
22820 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72  _count(S)] inter
22830 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
22840 20 20 20 20 20 20 20 20 20 74 68 65 20 6c 61 72           the lar
22850 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 61 6c  gest index of al
22860 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  l SQL parameters
22870 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
22880 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
22890 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30  atement] S, or 0
228a0 20 69 66 20 53 20 63 6f 6e 74 61 69 6e 73 20 6e   if S contains n
228b0 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  o SQL parameters
228c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
228d0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
228e0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
228f0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
22900 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
22910 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20   Host Parameter 
22920 7b 48 31 33 36 32 30 7d 20 3c 53 37 30 33 30 30  {H13620} <S70300
22930 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  >.**.** This rou
22940 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
22950 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61  ointer to the na
22960 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a  me of the n-th.*
22970 2a 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  * [SQL parameter
22980 5d 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] in a [prepared
22990 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
229a0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
229b0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
229c0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
229d0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
229e0 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
229f0 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
22a00 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
22a10 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
22a20 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
22a30 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
22a40 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
22a50 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
22a60 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
22a70 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
22a80 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
22a90 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65  ame..** Paramete
22aa0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
22ab0 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
22ac0 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
22ad0 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
22ae0 6e 64 20 61 72 65 20 61 6c 73 6f 20 72 65 66 65  nd are also refe
22af0 72 72 65 64 20 74 6f 20 61 73 20 22 61 6e 6f 6e  rred to as "anon
22b00 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
22b10 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  "..**.** The fir
22b20 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
22b30 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
22b40 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
22b50 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e  * If the value n
22b60 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
22b70 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20   or if the n-th 
22b80 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
22b90 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
22ba0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
22bb0 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73    The returned s
22bc0 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61  tring is.** alwa
22bd0 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f  ys in UTF-8 enco
22be0 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ding even if the
22bf0 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
22c00 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   was.** original
22c10 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ly specified as 
22c20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74  UTF-16 in [sqlit
22c30 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
22c40 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  or.** [sqlite3_p
22c50 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
22c60 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
22c70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
22c80 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
22c90 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
22ca0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
22cb0 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
22cc0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
22cd0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
22ce0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
22cf0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 32  TS:.**.** {H1362
22d00 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
22d10 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
22d20 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ame(S,N)] interf
22d30 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
22d40 20 20 20 20 20 20 20 20 61 20 55 54 46 2d 38 20          a UTF-8 
22d50 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
22d60 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
22d70 20 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a   parameter in.**
22d80 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70            the [p
22d90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22da0 74 5d 20 53 20 68 61 76 69 6e 67 20 69 6e 64 65  t] S having inde
22db0 78 20 4e 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  x N, or.**      
22dc0 20 20 20 20 4e 55 4c 4c 20 69 66 20 74 68 65 72      NULL if ther
22dd0 65 20 69 73 20 6e 6f 20 53 51 4c 20 70 61 72 61  e is no SQL para
22de0 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64 65 78  meter with index
22df0 20 4e 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20   N or if the.** 
22e00 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74           paramet
22e10 65 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20  er with index N 
22e20 69 73 20 61 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20  is an anonymous 
22e30 70 61 72 61 6d 65 74 65 72 20 22 3f 22 2e 0a 2a  parameter "?"..*
22e40 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
22e50 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
22e60 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
22e70 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
22e80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22e90 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
22ea0 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
22eb0 6e 20 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d 20  n Name {H13640} 
22ec0 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52  <S70300>.**.** R
22ed0 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
22ee0 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
22ef0 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
22f00 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65  me.  The.** inde
22f10 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
22f20 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
22f30 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
22f40 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
22f50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
22f60 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
22f70 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a  nd()].  A zero.*
22f80 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
22f90 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
22fa0 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
22fb0 20 20 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a    The parameter.
22fc0 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
22fd0 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
22fe0 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
22ff0 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
23000 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
23010 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
23020 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
23030 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
23040 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
23050 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
23060 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
23070 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
23080 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
23090 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
230a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
230b0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
230c0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
230d0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 34 31  S:.**.** {H13641
230e0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
230f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
23100 64 65 78 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  dex(S,N)] interf
23110 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
23120 20 20 20 20 20 20 20 20 74 68 65 20 69 6e 64 65          the inde
23130 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74  x of SQL paramet
23140 65 72 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  er in the [prepa
23150 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
23160 2a 20 20 20 20 20 20 20 20 20 20 53 20 77 68 6f  *          S who
23170 73 65 20 6e 61 6d 65 20 6d 61 74 63 68 65 73 20  se name matches 
23180 74 68 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67  the UTF-8 string
23190 20 4e 2c 20 6f 72 20 30 20 69 66 20 74 68 65 72   N, or 0 if ther
231a0 65 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  e is.**         
231b0 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e   no match..*/.in
231c0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
231d0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
231e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
231f0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
23200 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23210 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
23220 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
23230 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 48  red Statement {H
23240 31 33 36 36 30 7d 20 3c 53 37 30 33 30 30 3e 0a  13660} <S70300>.
23250 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74  **.** Contrary t
23260 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
23270 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
23280 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
23290 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
232a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
232b0 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
232c0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
232d0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 55 73  tatement]..** Us
232e0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
232f0 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
23300 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
23310 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ULL..**.** INVAR
23320 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
23330 33 36 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3661} The [sqlit
23340 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
23350 73 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  s(S)] interface 
23360 72 65 73 65 74 73 20 61 6c 6c 20 53 51 4c 0a 2a  resets all SQL.*
23370 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
23380 65 74 65 72 20 62 69 6e 64 69 6e 67 73 20 69 6e  eter bindings in
23390 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
233a0 74 61 74 65 6d 65 6e 74 5d 20 53 20 62 61 63 6b  tatement] S back
233b0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
233c0 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
233d0 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
233e0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
233f0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
23400 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
23410 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37  Result Set {H137
23420 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  10} <S10700>.**.
23430 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75  ** Return the nu
23440 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
23450 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
23460 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
23470 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
23480 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20  tatement]. This 
23490 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
234a0 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e  0 if pStmt is an
234b0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
234c0 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  t that does not 
234d0 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72  return data (for
234e0 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
234f0 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ATE])..**.** INV
23500 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
23510 48 31 33 37 31 31 7d 20 54 68 65 20 5b 73 71 6c  H13711} The [sql
23520 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
23530 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
23540 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
23550 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  er of.**        
23560 20 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65    columns in the
23570 20 72 65 73 75 6c 74 20 73 65 74 20 67 65 6e 65   result set gene
23580 72 61 74 65 64 20 62 79 20 74 68 65 20 5b 70 72  rated by the [pr
23590 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
235a0 5d 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] S,.**         
235b0 20 6f 72 20 30 20 69 66 20 53 20 64 6f 65 73 20   or 0 if S does 
235c0 6e 6f 74 20 67 65 6e 65 72 61 74 65 20 61 20 72  not generate a r
235d0 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e  esult set..*/.in
235e0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
235f0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
23600 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
23610 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
23620 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
23630 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37  Result Set {H137
23640 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  20} <S10700>.**.
23650 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
23660 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
23670 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
23680 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
23690 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
236a0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
236b0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
236c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   The sqlite3_col
236d0 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
236e0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
236f0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
23700 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
23710 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
23720 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
23730 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
23740 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
23750 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
23760 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
23770 6e 67 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ng.  The first p
23780 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
23790 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
237a0 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
237b0 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
237c0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
237d0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
237e0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
237f0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54  olumn number.  T
23800 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
23810 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
23820 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  **.** The return
23830 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
23840 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
23850 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
23860 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23870 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
23880 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
23890 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
238a0 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
238b0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
238c0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73  lumn_name() or s
238d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
238e0 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61  me16() on the sa
238f0 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
23900 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   If sqlite3_mall
23910 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
23920 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
23930 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
23940 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
23950 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
23960 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
23970 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
23980 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
23990 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
239a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  .**.** The name 
239b0 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
239c0 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
239d0 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
239e0 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
239f0 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
23a00 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
23a10 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
23a20 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
23a30 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
23a40 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
23a50 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
23a60 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
23a70 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
23a80 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
23a90 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  t..**.** INVARIA
23aa0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  NTS:.**.** {H137
23ab0 32 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  21} A successful
23ac0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
23ad0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
23ae0 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a  mn_name(S,N)].**
23af0 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
23b00 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
23b10 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 74 68 20  name of the Nth 
23b20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20  column (where 0 
23b30 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  is.**          t
23b40 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
23b50 6d 6e 29 20 66 6f 72 20 74 68 65 20 72 65 73 75  mn) for the resu
23b60 6c 74 20 73 65 74 20 6f 66 20 74 68 65 0a 2a 2a  lt set of the.**
23b70 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
23b80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
23b90 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   as a zero-termi
23ba0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
23bb0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32  ng..**.** {H1372
23bc0 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  3} A successful 
23bd0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
23be0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
23bf0 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 0a 2a  n_name16(S,N)].*
23c00 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
23c10 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
23c20 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 74 68   name of the Nth
23c30 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20 30   column (where 0
23c40 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
23c50 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  the leftmost col
23c60 75 6d 6e 29 20 66 6f 72 20 74 68 65 20 72 65 73  umn) for the res
23c70 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 0a 2a  ult set of the.*
23c80 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
23c90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
23ca0 53 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  S as a zero-term
23cb0 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 73 74  inated UTF-16 st
23cc0 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
23cd0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
23ce0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
23cf0 20 7b 48 31 33 37 32 34 7d 20 54 68 65 20 5b 73   {H13724} The [s
23d00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
23d10 6d 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  me()] and [sqlit
23d20 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
23d30 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
23d40 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72  interfaces retur
23d50 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
23d60 20 69 66 20 74 68 65 79 20 61 72 65 20 75 6e 61   if they are una
23d70 62 6c 65 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ble to.**       
23d80 20 20 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f     allocate memo
23d90 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 69 72  ry to hold their
23da0 20 6e 6f 72 6d 61 6c 20 72 65 74 75 72 6e 20 73   normal return s
23db0 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  trings..**.** {H
23dc0 31 33 37 32 35 7d 20 49 66 20 74 68 65 20 4e 20  13725} If the N 
23dd0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
23de0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
23df0 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20  e(S,N)] or.**   
23e00 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
23e10 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c  column_name16(S,
23e20 4e 29 5d 20 69 73 20 6f 75 74 20 6f 66 20 72 61  N)] is out of ra
23e30 6e 67 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  nge, then the.**
23e40 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
23e50 61 63 65 73 20 72 65 74 75 72 6e 20 61 20 4e 55  aces return a NU
23e60 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
23e70 2a 20 7b 48 31 33 37 32 36 7d 20 54 68 65 20 73  * {H13726} The s
23e80 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
23e90 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
23ea0 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 61 6e  mn_name(S,N)] an
23eb0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
23ec0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
23ed0 6d 65 31 36 28 53 2c 4e 29 5d 20 61 72 65 20 76  me16(S,N)] are v
23ee0 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e  alid until the n
23ef0 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ext.**          
23f00 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 72  call to either r
23f10 6f 75 74 69 6e 65 20 77 69 74 68 20 74 68 65 20  outine with the 
23f20 73 61 6d 65 20 53 20 61 6e 64 20 4e 20 70 61 72  same S and N par
23f30 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20  ameters.**      
23f40 20 20 20 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71      or until [sq
23f50 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
23f60 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2a  )] is called..**
23f70 0a 2a 2a 20 7b 48 31 33 37 32 37 7d 20 57 68 65  .** {H13727} Whe
23f80 6e 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  n a result colum
23f90 6e 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  n of a [SELECT] 
23fa0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6e 74 61 69  statement contai
23fb0 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ns.**          a
23fc0 6e 20 41 53 20 63 6c 61 75 73 65 2c 20 74 68 65  n AS clause, the
23fd0 20 6e 61 6d 65 20 6f 66 20 74 68 61 74 20 63 6f   name of that co
23fe0 6c 75 6d 6e 20 69 73 20 74 68 65 20 69 64 65 6e  lumn is the iden
23ff0 74 69 66 69 65 72 0a 2a 2a 20 20 20 20 20 20 20  tifier.**       
24000 20 20 20 74 6f 20 74 68 65 20 72 69 67 68 74 20     to the right 
24010 6f 66 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72  of the AS keywor
24020 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  d..*/.const char
24030 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
24040 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
24050 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
24060 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
24070 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
24080 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24090 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
240a0 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
240b0 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
240c0 20 52 65 73 75 6c 74 20 7b 48 31 33 37 34 30 7d   Result {H13740}
240d0 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10700>.**.** 
240e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
240f0 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
24100 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74  o determine what
24110 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a   column of what.
24120 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63  ** table in whic
24130 68 20 64 61 74 61 62 61 73 65 20 61 20 72 65 73  h database a res
24140 75 6c 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  ult of a [SELECT
24150 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65  ] statement come
24160 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e  s from..** The n
24170 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
24180 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
24190 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
241a0 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
241b0 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
241c0 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54  TF-16 string.  T
241d0 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
241e0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
241f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
24200 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
24210 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
24220 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
24230 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
24240 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
24250 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
24260 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  me..** The retur
24270 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
24280 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
24290 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
242a0 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
242b0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
242c0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
242d0 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
242e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
242f0 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
24300 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
24310 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
24320 20 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72   The names retur
24330 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
24340 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
24350 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
24360 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
24370 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
24380 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
24390 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c  ument to the fol
243a0 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20  lowing calls is 
243b0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
243c0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65  ement]..** These
243d0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
243e0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
243f0 6f 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  out the Nth colu
24400 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
24410 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
24420 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
24430 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
24440 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
24450 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
24460 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
24470 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
24480 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
24490 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
244a0 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
244b0 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
244c0 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
244d0 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
244e0 4c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  L.  These routin
244f0 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
24500 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
24510 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
24520 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
24530 20 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65    Otherwise, the
24540 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  y return the nam
24550 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
24560 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
24570 65 0a 2a 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  e.** and column 
24580 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
24590 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  t column was ext
245a0 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
245b0 2a 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  ** As with all o
245c0 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
245d0 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65  , those postfixe
245e0 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
245f0 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
24600 6f 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68  oded strings, th
24610 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
24620 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 20  s return UTF-8. 
24630 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  {END}.**.** Thes
24640 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
24650 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
24660 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
24670 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
24680 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
24690 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
246a0 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
246b0 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
246c0 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 0a  .**.** {A13751}.
246d0 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
246e0 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
246f0 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
24700 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
24710 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
24720 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
24730 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
24740 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
24750 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
24760 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
24770 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
24780 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  NTS:.**.** {H137
24790 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  41} The [sqlite3
247a0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
247b0 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65  _name(S,N)] inte
247c0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69  rface returns ei
247d0 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
247e0 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d   the UTF-8 zero-
247f0 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
24800 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
24810 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a  from which the.*
24820 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
24830 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
24840 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
24850 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78  atement] S is ex
24860 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20  tracted,.**     
24870 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20       or NULL if 
24880 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
24890 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c  f S is a general
248a0 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20   expression.**  
248b0 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e          or if un
248c0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
248d0 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65   memory to store
248e0 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a   the name..**.**
248f0 20 7b 48 31 33 37 34 32 7d 20 54 68 65 20 5b 73   {H13742} The [s
24900 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
24910 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 53 2c  tabase_name16(S,
24920 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
24930 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
24940 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
24950 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
24960 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69  order zero-termi
24970 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68  nated name of th
24980 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20  e database.**   
24990 20 20 20 20 20 20 20 66 72 6f 6d 20 77 68 69 63         from whic
249a0 68 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  h the Nth result
249b0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b   column of the [
249c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
249d0 6e 74 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20 20  nt] S is.**     
249e0 20 20 20 20 20 65 78 74 72 61 63 74 65 64 2c 20       extracted, 
249f0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e  or NULL if the N
24a00 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
24a10 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72  s a general expr
24a20 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ession.**       
24a30 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20     or if unable 
24a40 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
24a50 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20  ry to store the 
24a60 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  name..**.** {H13
24a70 37 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  743} The [sqlite
24a80 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
24a90 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ame(S,N)] interf
24aa0 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
24ab0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
24ac0 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  he UTF-8 zero-te
24ad0 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
24ae0 20 74 68 65 20 74 61 62 6c 65 20 66 72 6f 6d 20   the table from 
24af0 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20  which the.**    
24b00 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74        Nth result
24b10 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b   column of the [
24b20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24b30 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74  nt] S is extract
24b40 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ed,.**          
24b50 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e  or NULL if the N
24b60 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
24b70 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72  s a general expr
24b80 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ession.**       
24b90 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20     or if unable 
24ba0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
24bb0 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20  ry to store the 
24bc0 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  name..**.** {H13
24bd0 37 34 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  744} The [sqlite
24be0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
24bf0 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65  ame16(S,N)] inte
24c00 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69  rface returns ei
24c10 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
24c20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69   the UTF-16 nati
24c30 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65  ve byte order ze
24c40 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
24c50 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  me of the table.
24c60 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d  **          from
24c70 20 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 72   which the Nth r
24c80 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
24c90 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
24ca0 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a  atement] S is.**
24cb0 20 20 20 20 20 20 20 20 20 20 65 78 74 72 61 63            extrac
24cc0 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20  ted, or NULL if 
24cd0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
24ce0 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c  f S is a general
24cf0 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20   expression.**  
24d00 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e          or if un
24d10 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
24d20 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65   memory to store
24d30 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a   the name..**.**
24d40 20 7b 48 31 33 37 34 35 7d 20 54 68 65 20 5b 73   {H13745} The [s
24d50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
24d60 69 67 69 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  igin_name(S,N)] 
24d70 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
24d80 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
24d90 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a       the UTF-8 z
24da0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
24db0 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ame of the table
24dc0 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69   column from whi
24dd0 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ch the.**       
24de0 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f     Nth result co
24df0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65  lumn of the [pre
24e00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24e10 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c   S is extracted,
24e20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
24e30 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20  NULL if the Nth 
24e40 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
24e50 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73   general express
24e60 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
24e70 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
24e80 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
24e90 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d  to store the nam
24ea0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 36  e..**.** {H13746
24eb0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
24ec0 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
24ed0 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  e16(S,N)] interf
24ee0 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
24ef0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
24f00 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  he UTF-16 native
24f10 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f   byte order zero
24f20 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65  -terminated name
24f30 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
24f40 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e            column
24f50 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
24f60 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
24f70 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  n of the.**     
24f80 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
24f90 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65  tatement] S is e
24fa0 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c  xtracted, or NUL
24fb0 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  L if the Nth col
24fc0 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  umn.**          
24fd0 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61  of S is a genera
24fe0 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  l expression or 
24ff0 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  if unable to all
25000 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ocate memory.** 
25010 20 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72           to stor
25020 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a  e the name..**.*
25030 2a 20 7b 48 31 33 37 34 38 7d 20 54 68 65 20 72  * {H13748} The r
25040 65 74 75 72 6e 20 76 61 6c 75 65 73 20 66 72 6f  eturn values fro
25050 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  m.**          [s
25060 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
25070 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
25080 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
25090 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20  terfaces].**    
250a0 20 20 20 20 20 20 61 72 65 20 76 61 6c 69 64 20        are valid 
250b0 66 6f 72 20 74 68 65 20 6c 69 66 65 74 69 6d 65  for the lifetime
250c0 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
250d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
250e0 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69           or unti
250f0 6c 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  l the encoding i
25100 73 20 63 68 61 6e 67 65 64 20 62 79 20 61 6e 6f  s changed by ano
25110 74 68 65 72 20 6d 65 74 61 64 61 74 61 0a 2a 2a  ther metadata.**
25120 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
25130 61 63 65 20 63 61 6c 6c 20 66 6f 72 20 74 68 65  ace call for the
25140 20 73 61 6d 65 20 70 72 65 70 61 72 65 64 20 73   same prepared s
25150 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
25160 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  umn..**.** ASSUM
25170 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
25180 31 33 37 35 31 7d 20 49 66 20 74 77 6f 20 6f 72  13751} If two or
25190 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
251a0 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
251b0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
251c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
251d0 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
251e0 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
251f0 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20  faces].**       
25200 20 20 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20     for the same 
25210 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25220 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
25230 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20  column.**       
25240 20 20 20 61 74 20 74 68 65 20 73 61 6d 65 20 74     at the same t
25250 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
25260 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
25270 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ed..*/.const cha
25280 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
25290 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
252a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
252b0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
252c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
252d0 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
252e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
252f0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
25300 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
25310 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
25320 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
25330 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
25340 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
25350 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
25360 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
25370 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
25380 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
25390 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
253a0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
253b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
253c0 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
253d0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
253e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
253f0 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
25400 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
25410 65 73 75 6c 74 20 7b 48 31 33 37 36 30 7d 20 3c  esult {H13760} <
25420 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S10700>.**.** Th
25430 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
25440 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
25450 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
25460 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
25470 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
25480 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
25490 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
254a0 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
254b0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
254c0 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
254d0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
254e0 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
254f0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
25500 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
25510 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
25520 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
25530 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20  s returned.  If 
25540 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
25550 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
25560 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
25570 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
25580 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
25590 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
255a0 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  d..** The return
255b0 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
255c0 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
255d0 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46  d. {END}.**.** F
255e0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
255f0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
25600 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
25610 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
25620 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
25630 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
25640 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
25650 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
25660 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
25670 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
25680 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
25690 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
256a0 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
256b0 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
256c0 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
256d0 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
256e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
256f0 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
25700 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
25710 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
25720 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
25730 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20  ime typing.  So 
25740 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
25750 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
25760 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
25770 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
25780 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
25790 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
257a0 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
257b0 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
257c0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
257d0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
257e0 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
257f0 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
25800 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
25810 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20  ic.  Type.** is 
25820 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
25830 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
25840 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
25850 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
25860 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
25870 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49   values..**.** I
25880 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
25890 20 7b 48 31 33 37 36 31 7d 20 20 41 20 73 75 63   {H13761}  A suc
258a0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
258b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
258c0 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20 72  decltype(S,N)] r
258d0 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20  eturns a.**     
258e0 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
258f0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
25900 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
25910 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74  e declared datat
25920 79 70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ype.**          
25930 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
25940 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72  lumn that appear
25950 73 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c  s as the Nth col
25960 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 0a 2a 2a  umn (numbered.**
25970 20 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20             from 
25980 30 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  0) of the result
25990 20 73 65 74 20 74 6f 20 74 68 65 20 5b 70 72 65   set to the [pre
259a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
259b0 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36   S..**.** {H1376
259c0 32 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 6c  2}  A successful
259d0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
259e0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
259f0 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20  e16(S,N)].**    
25a00 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61         returns a
25a10 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
25a20 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
25a30 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67  yte order string
25a40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f  .**           co
25a50 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63  ntaining the dec
25a60 6c 61 72 65 64 20 64 61 74 61 74 79 70 65 20 6f  lared datatype o
25a70 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
25a80 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72 73 0a  mn that appears.
25a90 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 20  **           as 
25aa0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28  the Nth column (
25ab0 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d 20 30 29  numbered from 0)
25ac0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
25ad0 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  et to the.**    
25ae0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
25af0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
25b00 2a 0a 2a 2a 20 7b 48 31 33 37 36 33 7d 20 20 49  *.** {H13763}  I
25b10 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
25b20 20 30 20 6f 72 20 4e 20 69 73 20 67 72 65 61 74   0 or N is great
25b30 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  er than or equal
25b40 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
25b50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
25b60 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 5b 70  olumns in the [p
25b70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25b80 74 5d 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20  t] S,.**        
25b90 20 20 20 6f 72 20 69 66 20 74 68 65 20 4e 74 68     or if the Nth
25ba0 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
25bb0 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
25bc0 20 73 75 62 71 75 65 72 79 20 72 61 74 68 65 72   subquery rather
25bd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
25be0 61 6e 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  an a table colum
25bf0 6e 2c 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72  n, or if a memor
25c00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
25c10 6c 75 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  lure.**         
25c20 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20    occurs during 
25c30 65 6e 63 6f 64 69 6e 67 20 63 6f 6e 76 65 72 73  encoding convers
25c40 69 6f 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  ions, then.**   
25c50 20 20 20 20 20 20 20 20 63 61 6c 6c 73 20 74 6f          calls to
25c60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
25c70 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20  _decltype(S,N)] 
25c80 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
25c90 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
25ca0 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d  decltype16(S,N)]
25cb0 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f   return NULL..*/
25cc0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
25cd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
25ce0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
25cf0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
25d00 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
25d10 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
25d20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
25d30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
25d40 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20  EF: Evaluate An 
25d50 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48  SQL Statement {H
25d60 31 33 32 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a  13200} <S10000>.
25d70 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
25d80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25d90 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
25da0 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
25db0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
25dc0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
25dd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
25de0 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
25df0 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
25e00 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
25e10 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
25e20 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
25e30 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
25e40 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
25e50 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
25e60 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
25e70 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
25e80 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
25e90 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
25ea0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
25eb0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
25ec0 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
25ed0 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
25ee0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
25ef0 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
25f00 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
25f10 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
25f20 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
25f30 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
25f40 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
25f50 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
25f60 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
25f70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
25f80 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
25f90 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
25fa0 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
25fb0 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
25fc0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
25fd0 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
25fe0 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
25ff0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
26000 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
26010 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
26020 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  d..**.** In the 
26030 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
26040 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
26050 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
26060 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
26070 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
26080 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
26090 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
260a0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
260b0 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65  SE]..** With the
260c0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
260d0 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
260e0 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
260f0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
26100 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
26110 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
26120 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
26130 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
26140 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
26150 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
26160 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
26170 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
26180 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
26190 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
261a0 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
261b0 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
261c0 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
261d0 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
261e0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
261f0 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
26200 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
26210 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
26220 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
26230 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
26240 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a  ccurs within a.*
26250 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
26260 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
26270 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
26280 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
26290 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
262a0 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  uing..**.** [SQL
262b0 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
262c0 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
262d0 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
262e0 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
262f0 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
26300 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
26310 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
26320 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
26330 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
26340 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
26350 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
26360 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
26370 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
26380 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
26390 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
263a0 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  te..**.** If the
263b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
263c0 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
263d0 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
263e0 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  then [SQLITE_ROW
263f0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
26400 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77   each time a new
26410 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20   row of data is 
26420 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73  ready for proces
26430 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63  sing by the.** c
26440 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65  aller. The value
26450 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  s may be accesse
26460 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c  d using the [col
26470 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
26480 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
26490 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
264a0 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
264b0 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
264c0 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
264d0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
264e0 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
264f0 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
26500 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
26510 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
26520 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
26530 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
26540 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
26550 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
26560 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
26570 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
26580 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
26590 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
265a0 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20  )]..** With the 
265b0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
265c0 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
265d0 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
265e0 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
265f0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
26600 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
26610 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
26620 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
26630 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
26640 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
26650 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
26660 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
26670 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26680 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22 20  ].  In the "v2" 
26690 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
266a0 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
266b0 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
266c0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
266d0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
266e0 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
266f0 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
26700 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
26710 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
26720 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
26730 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
26740 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
26750 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26760 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
26770 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
26780 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
26790 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
267a0 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
267b0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
267c0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
267d0 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
267e0 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
267f0 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
26800 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
26810 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
26820 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
26830 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
26840 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
26850 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
26860 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c  in time..**.** <
26870 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
26880 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
26890 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
268a0 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
268b0 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
268c0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
268d0 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
268e0 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
268f0 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
26900 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
26910 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
26920 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
26930 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
26940 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
26950 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
26960 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
26970 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
26980 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
26990 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
269a0 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
269b0 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
269c0 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
269d0 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
269e0 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
269f0 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
26a00 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
26a10 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
26a20 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
26a30 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
26a40 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
26a50 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
26a60 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
26a70 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
26a80 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
26a90 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
26aa0 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
26ab0 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
26ac0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
26ad0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
26ae0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
26af0 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
26b00 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
26b10 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
26b20 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
26b30 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
26b40 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
26b50 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
26b60 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
26b70 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
26b80 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 32 30  TS:.**.** {H1320
26b90 32 7d 20 20 49 66 20 74 68 65 20 5b 70 72 65 70  2}  If the [prep
26ba0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
26bb0 53 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65  S is ready to be
26bc0 20 72 75 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20   run, then.**   
26bd0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
26be0 5f 73 74 65 70 28 53 29 5d 20 61 64 76 61 6e 63  _step(S)] advanc
26bf0 65 73 20 74 68 61 74 20 70 72 65 70 61 72 65 64  es that prepared
26c00 20 73 74 61 74 65 6d 65 6e 74 20 75 6e 74 69 6c   statement until
26c10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f  .**           co
26c20 6d 70 6c 65 74 69 6f 6e 20 6f 72 20 75 6e 74 69  mpletion or unti
26c30 6c 20 69 74 20 69 73 20 72 65 61 64 79 20 74 6f  l it is ready to
26c40 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 20   return another 
26c50 72 6f 77 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  row of the.**   
26c60 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73          result s
26c70 65 74 2c 20 6f 72 20 75 6e 74 69 6c 20 61 6e 20  et, or until an 
26c80 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
26c90 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 0a  pt | interrupt].
26ca0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 20  **           or 
26cb0 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
26cc0 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b   occurs..**.** {
26cd0 48 31 35 33 30 34 7d 20 20 57 68 65 6e 20 61 20  H15304}  When a 
26ce0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
26cf0 5f 73 74 65 70 28 53 29 5d 20 63 61 75 73 65 73  _step(S)] causes
26d00 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
26d10 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20  tatement].**    
26d20 20 20 20 20 20 20 20 53 20 74 6f 20 72 75 6e 20         S to run 
26d30 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c 20 74  to completion, t
26d40 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
26d50 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  rns [SQLITE_DONE
26d60 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 36  ]..**.** {H15306
26d70 7d 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74  }  When a call t
26d80 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
26d90 53 29 5d 20 73 74 6f 70 73 20 62 65 63 61 75 73  S)] stops becaus
26da0 65 20 69 74 20 69 73 20 72 65 61 64 79 20 74 6f  e it is ready to
26db0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
26dc0 74 75 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77  turn another row
26dd0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
26de0 65 74 2c 20 69 74 20 72 65 74 75 72 6e 73 20 5b  et, it returns [
26df0 53 51 4c 49 54 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a  SQLITE_ROW]..**.
26e00 2a 2a 20 7b 48 31 35 33 30 38 7d 20 20 49 66 20  ** {H15308}  If 
26e10 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
26e20 65 33 5f 73 74 65 70 28 53 29 5d 20 65 6e 63 6f  e3_step(S)] enco
26e30 75 6e 74 65 72 73 20 61 6e 0a 2a 2a 20 20 20 20  unters an.**    
26e40 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
26e50 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65  interrupt | inte
26e60 72 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d  rrupt] or a run-
26e70 74 69 6d 65 20 65 72 72 6f 72 2c 0a 2a 2a 20 20  time error,.**  
26e80 20 20 20 20 20 20 20 20 20 69 74 20 72 65 74 75           it retu
26e90 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
26ea0 74 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 68  te error code th
26eb0 61 74 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  at is not one of
26ec0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53  .**           [S
26ed0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 5b 53 51 4c 49  QLITE_OK], [SQLI
26ee0 54 45 5f 52 4f 57 5d 2c 20 6f 72 20 5b 53 51 4c  TE_ROW], or [SQL
26ef0 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a  ITE_DONE]..**.**
26f00 20 7b 48 31 35 33 31 30 7d 20 20 49 66 20 61 6e   {H15310}  If an
26f10 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
26f20 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d  upt | interrupt]
26f30 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65   or a run-time e
26f40 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rror.**         
26f50 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20    occurs during 
26f60 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
26f70 65 33 5f 73 74 65 70 28 53 29 5d 0a 2a 2a 20 20  e3_step(S)].**  
26f80 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20 5b           for a [
26f90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26fa0 6e 74 5d 20 53 20 63 72 65 61 74 65 64 20 75 73  nt] S created us
26fb0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
26fc0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
26fd0 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
26fe0 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  are()] or.**    
26ff0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
27000 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
27010 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
27020 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a  returns either.*
27030 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  *           [SQL
27040 49 54 45 5f 45 52 52 4f 52 5d 2c 20 5b 53 51 4c  ITE_ERROR], [SQL
27050 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72 20 5b 53  ITE_BUSY], or [S
27060 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a  QLITE_MISUSE]..*
27070 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
27080 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
27090 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
270a0 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
270b0 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
270c0 74 20 73 65 74 20 7b 48 31 33 37 37 30 7d 20 3c  t set {H13770} <
270d0 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65  S10700>.**.** Re
270e0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
270f0 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68   of values in th
27100 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
27110 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e   the result set.
27120 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
27130 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 37 31  S:.**.** {H13771
27140 7d 20 20 41 66 74 65 72 20 61 20 63 61 6c 6c 20  }  After a call 
27150 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
27160 28 53 29 5d 20 74 68 61 74 20 72 65 74 75 72 6e  (S)] that return
27170 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 0a  s [SQLITE_ROW],.
27180 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65  **           the
27190 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
271a0 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e 65  ount(S)] routine
271b0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65   will return the
271c0 20 73 61 6d 65 20 76 61 6c 75 65 0a 2a 2a 20 20   same value.**  
271d0 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20           as the 
271e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
271f0 63 6f 75 6e 74 28 53 29 5d 20 66 75 6e 63 74 69  count(S)] functi
27200 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 37  on..**.** {H1377
27210 32 7d 20 20 41 66 74 65 72 20 5b 73 71 6c 69 74  2}  After [sqlit
27220 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
27230 72 65 74 75 72 6e 65 64 20 61 6e 79 20 76 61 6c  returned any val
27240 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a  ue other than.**
27250 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49             [SQLI
27260 54 45 5f 52 4f 57 5d 20 6f 72 20 62 65 66 6f 72  TE_ROW] or befor
27270 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
27280 53 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  S)] has been cal
27290 6c 65 64 20 6f 6e 20 74 68 65 0a 2a 2a 20 20 20  led on the.**   
272a0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
272b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f 72  d statement] for
272c0 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
272d0 73 69 6e 63 65 20 69 74 20 77 61 73 0a 2a 2a 20  since it was.** 
272e0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
272f0 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
27300 70 61 72 65 64 5d 20 6f 72 20 5b 73 71 6c 69 74  pared] or [sqlit
27310 65 33 5f 72 65 73 65 74 20 7c 20 72 65 73 65 74  e3_reset | reset
27320 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ],.**           
27330 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  the [sqlite3_dat
27340 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74  a_count(S)] rout
27350 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ine returns zero
27360 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
27370 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
27380 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
27390 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
273a0 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
273b0 61 74 61 74 79 70 65 73 20 7b 48 31 30 32 36 35  atatypes {H10265
273c0 7d 20 3c 53 31 30 31 31 30 3e 3c 53 31 30 31 32  } <S10110><S1012
273d0 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
273e0 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
273f0 2a 20 7b 48 31 30 32 36 36 7d 20 45 76 65 72 79  * {H10266} Every
27400 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
27410 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
27420 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
27430 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
27440 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
27450 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
27460 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
27470 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
27480 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
27490 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
274a0 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
274b0 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e  ULL.** </ul> {EN
274c0 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  D}.**.** These c
274d0 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
274e0 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
274f0 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
27500 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
27510 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
27520 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
27530 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
27540 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
27550 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
27560 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
27570 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
27580 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
27590 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
275a0 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
275b0 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
275c0 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
275d0 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
275e0 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
275f0 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
27600 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
27610 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
27620 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
27630 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
27640 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
27650 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
27660 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
27670 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
27680 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
27690 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
276a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
276b0 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
276c0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
276d0 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
276e0 20 51 75 65 72 79 20 7b 48 31 33 38 30 30 7d 20   Query {H13800} 
276f0 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S10700>.** KEYW
27700 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
27710 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
27720 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
27730 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72  ines form the "r
27740 65 73 75 6c 74 20 73 65 74 20 71 75 65 72 79 22  esult set query"
27750 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
27760 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
27770 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
27780 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
27790 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
277a0 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
277b0 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
277c0 79 2e 20 20 49 6e 20 65 76 65 72 79 20 63 61 73  y.  In every cas
277d0 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
277e0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
277f0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
27800 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27810 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
27820 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
27830 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
27840 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
27850 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
27860 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
27870 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
27880 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
27890 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
278a0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
278b0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
278c0 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
278d0 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
278e0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c  returned.  The l
278f0 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
27900 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
27910 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
27920 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
27930 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
27940 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
27950 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
27960 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
27970 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
27980 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
27990 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
279a0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
279b0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
279c0 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
279d0 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
279e0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
279f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
27a00 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
27a10 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
27a20 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
27a30 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
27a40 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
27a50 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
27a60 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
27a70 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
27a80 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
27a90 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
27aa0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
27ab0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
27ac0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
27ad0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
27ae0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
27af0 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
27b00 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
27b10 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
27b20 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
27b30 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
27b40 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
27b50 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
27b60 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
27b70 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
27b80 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
27b90 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
27ba0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
27bb0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
27bc0 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
27bd0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
27be0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
27bf0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   The sqlite3_col
27c00 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
27c10 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
27c20 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
27c30 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
27c40 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
27c50 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
27c60 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
27c70 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72  lumn.  The retur
27c80 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
27c90 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
27ca0 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
27cb0 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
27cc0 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
27cd0 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
27ce0 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
27cf0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
27d00 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
27d10 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
27d20 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
27d30 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
27d40 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
27d50 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
27d60 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
27d70 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
27d80 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
27d90 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
27da0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
27db0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
27dc0 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
27dd0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
27de0 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
27df0 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
27e00 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
27e10 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
27e20 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
27e30 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
27e40 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
27e50 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
27e60 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
27e70 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
27e80 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
27e90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
27ea0 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
27eb0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66  or string..** If
27ec0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
27ed0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
27ee0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
27ef0 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
27f00 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
27f10 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
27f20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
27f30 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
27f40 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  ..** If the resu
27f50 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
27f60 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
27f70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
27f80 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
27f90 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
27fa0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
27fb0 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
27fc0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
27fd0 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
27fe0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
27ff0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65  t string..** The
28000 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
28010 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
28020 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
28030 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a  ator at the end.
28040 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
28050 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20  .  For clarity: 
28060 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
28070 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ed is the number
28080 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
28090 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
280a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
280b0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
280c0 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
280d0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
280e0 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
280f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
28100 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65  t16(),.** even e
28110 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72  mpty strings, ar
28120 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65  e always zero te
28130 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 72  rminated.  The r
28140 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
28150 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
28160 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
28170 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
28180 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
28190 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73  .** pointer, pos
281a0 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c  sibly even a NUL
281b0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
281c0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   The sqlite3_col
281d0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f  umn_bytes16() ro
281e0 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
281f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
28200 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75  mn_bytes().** bu
28210 74 20 6c 65 61 76 65 73 20 74 68 65 20 72 65 73  t leaves the res
28220 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e  ult in UTF-16 in
28230 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
28240 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54  er instead of UT
28250 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 72 6f  F-8..** The zero
28260 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e   terminator is n
28270 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ot included in t
28280 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a  his count..**.**
28290 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75   The object retu
282a0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
282b0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
282c0 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
282d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
282e0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41  alue] object.  A
282f0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
28300 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28310 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ct.** may only b
28320 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c  e used with [sql
28330 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
28340 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
28350 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
28360 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
28370 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28380 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
28390 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
283a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
283b0 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
283c0 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
283d0 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
283e0 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
283f0 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  ike [sqlite3_val
28400 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
28410 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
28420 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
28430 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
28440 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
28450 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
28460 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
28470 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74  utines attempt t
28480 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
28490 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70  lue where approp
284a0 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  riate.  For.** e
284b0 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
284c0 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
284d0 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
284e0 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
284f0 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
28500 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
28510 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
28520 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
28530 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
28540 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
28550 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c  cally.  The foll
28560 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
28570 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
28580 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ons.** that are 
28590 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
285a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
285b0 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
285c0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
285d0 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
285e0 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
285f0 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
28600 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
28610 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
28620 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
28630 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
28640 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
28650 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
28660 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
28670 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
28680 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
28690 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
286a0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
286b0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
286c0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
286d0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
286e0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
286f0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
28700 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
28710 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
28720 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
28730 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
28740 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
28750 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
28760 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
28770 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
28780 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
28790 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
287a0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
287b0 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54  me as INTEGER->T
287c0 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
287d0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
287e0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
287f0 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20  vert from float 
28800 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  to integer.** <t
28810 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
28820 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
28830 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
28840 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
28850 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
28860 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
28870 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
28880 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a  s FLOAT->TEXT.**
28890 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
288a0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
288b0 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28    <td> Use atoi(
288c0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
288d0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
288e0 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61  AT    <td> Use a
288f0 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
28900 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
28910 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
28920 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
28930 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
28940 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
28950 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
28960 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28  T then use atoi(
28970 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
28980 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  LOB    <td>  FLO
28990 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
289a0 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
289b0 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  use atof().** <t
289c0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
289d0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
289e0 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
289f0 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
28a00 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
28a10 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
28a20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
28a30 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66   above makes ref
28a40 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61  erence to standa
28a50 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e  rd C library fun
28a60 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a  ctions atoi().**
28a70 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51   and atof().  SQ
28a80 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65  Lite does not re
28a90 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66  ally use these f
28aa0 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61  unctions.  It ha
28ab0 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75  s its.** own equ
28ac0 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c  ivalent internal
28ad0 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20   routines.  The 
28ae0 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28  atoi() and atof(
28af0 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75  ) names are.** u
28b00 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65  sed in the table
28b10 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64   for brevity and
28b20 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72   because they ar
28b30 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f  e familiar to mo
28b40 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d  st.** C programm
28b50 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ers..**.** Note 
28b60 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
28b70 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
28b80 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
28b90 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
28ba0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
28bb0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
28bc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
28bd0 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
28be0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28bf0 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
28c00 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20  invalidated..** 
28c10 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
28c20 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
28c30 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
28c40 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
28c50 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
28c60 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
28c70 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
28c80 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c   content is a BL
28c90 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  OB and sqlite3_c
28ca0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a  olumn_text() or.
28cb0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
28cc0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
28cd0 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65  is called.  A ze
28ce0 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69  ro-terminator mi
28cf0 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64  ght.**      need
28d00 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20   to be added to 
28d10 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e  the string.</li>
28d20 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
28d30 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
28d40 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
28d50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
28d60 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
28d70 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
28d80 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
28d90 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
28da0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
28db0 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
28dc0 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20  UTF-16.</li>.** 
28dd0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
28de0 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
28df0 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  16 text and sqli
28e00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28e10 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
28e20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
28e30 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
28e40 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
28e50 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
28e60 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
28e70 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
28e80 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20  .** Conversions 
28e90 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
28ea0 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
28eb0 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
28ec0 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
28ed0 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
28ee0 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
28ef0 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
28f00 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
28f10 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
28f20 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
28f30 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20  inter points to 
28f40 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
28f50 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
28f60 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
28f70 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
28f80 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
28f90 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
28fa0 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
28fb0 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
28fc0 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
28fd0 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
28fe0 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
28ff0 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
29000 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73  e safest and eas
29010 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72  iest to remember
29020 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
29030 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
29040 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
29050 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
29060 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
29070 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
29080 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
29090 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
290a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
290b0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
290c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
290d0 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
290e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
290f0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
29100 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
29110 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
29120 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
29130 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
29140 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
29150 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
29160 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
29170 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
29180 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
29190 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
291a0 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
291b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
291c0 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
291d0 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
291e0 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
291f0 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
29200 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
29210 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
29220 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29230 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
29240 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
29250 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
29260 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
29270 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29280 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
29290 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
292a0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
292b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
292c0 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
292d0 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
292e0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
292f0 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
29300 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
29310 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
29320 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  ()..**.** The po
29330 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
29340 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
29350 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
29360 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
29370 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
29380 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
29390 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
293a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
293b0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
293c0 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
293d0 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79  led.  The memory
293e0 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
293f0 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
29400 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
29410 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
29420 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20    Do <b>not</b> 
29430 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
29440 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73  s returned.** [s
29450 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
29460 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
29470 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
29480 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  etc. into.** [sq
29490 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
294a0 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79  *.** If a memory
294b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
294c0 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
294d0 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
294e0 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
294f0 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
29500 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
29510 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
29520 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
29530 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
29540 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
29550 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
29560 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
29570 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
29580 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
29590 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
295a0 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
295b0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
295c0 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  EM]..**.** INVAR
295d0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
295e0 33 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  3803} The [sqlit
295f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53  e3_column_blob(S
29600 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
29610 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
29620 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
29630 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
29640 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
29650 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
29660 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65          the [pre
29670 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29680 20 53 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61   S into a BLOB a
29690 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
296a0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  a.**          po
296b0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e  inter to the con
296c0 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a  verted value..**
296d0 0a 2a 2a 20 7b 48 31 33 38 30 36 7d 20 54 68 65  .** {H13806} The
296e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
296f0 5f 62 79 74 65 73 28 53 2c 4e 29 5d 20 69 6e 74  _bytes(S,N)] int
29700 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
29710 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
29720 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
29730 6e 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  n the BLOB or st
29740 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20  ring (exclusive 
29750 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
29760 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74     zero terminat
29770 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67  or on the string
29780 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  ) that was retur
29790 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20  ned by the.**   
297a0 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65         most rece
297b0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
297c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
297d0 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  S,N)] or.**     
297e0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
297f0 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 2e  lumn_text(S,N)].
29800 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 39 7d 20  .**.** {H13809} 
29810 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
29820 75 6d 6e 5f 62 79 74 65 73 31 36 28 53 2c 4e 29  umn_bytes16(S,N)
29830 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
29840 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rns the.**      
29850 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79      number of by
29860 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
29870 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20  g (exclusive of 
29880 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
29890 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
298a0 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74  on the string) t
298b0 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
298c0 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   by the.**      
298d0 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20      most recent 
298e0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
298f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53  _column_text16(S
29900 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ,N)]..**.** {H13
29910 38 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  812} The [sqlite
29920 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
29930 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
29940 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
29950 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
29960 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
29970 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
29980 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65  sult set for the
29990 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
299a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
299b0 5d 20 53 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74  ] S into a float
299c0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
299d0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
299e0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
299f0 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a  f that value..**
29a00 0a 2a 2a 20 7b 48 31 33 38 31 35 7d 20 54 68 65  .** {H13815} The
29a10 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
29a20 5f 69 6e 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72  _int(S,N)] inter
29a30 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
29a40 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
29a50 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
29a60 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
29a70 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
29a80 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
29a90 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
29aa0 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
29ab0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
29ac0 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20  teger and.**    
29ad0 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 74 68        returns th
29ae0 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20  e lower 32 bits 
29af0 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  of that integer.
29b00 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 38 7d 20  .**.** {H13818} 
29b10 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
29b20 75 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e 29 5d 20  umn_int64(S,N)] 
29b30 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
29b40 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
29b50 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
29b60 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
29b70 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
29b80 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  et for the.**   
29b90 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
29ba0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
29bb0 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e  to a 64-bit sign
29bc0 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a  ed integer and.*
29bd0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
29be0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61  ns a copy of tha
29bf0 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
29c00 20 7b 48 31 33 38 32 31 7d 20 54 68 65 20 5b 73   {H13821} The [s
29c10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
29c20 78 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  xt(S,N)] interfa
29c30 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
29c40 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
29c50 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
29c60 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
29c70 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
29c80 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
29c90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29ca0 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65  ent] S into a ze
29cb0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
29cc0 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  F-8.**          
29cd0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
29ce0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
29cf0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
29d00 2a 2a 20 7b 48 31 33 38 32 34 7d 20 54 68 65 20  ** {H13824} The 
29d10 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
29d20 74 65 78 74 31 36 28 53 2c 4e 29 5d 20 69 6e 74  text16(S,N)] int
29d30 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
29d40 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
29d50 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
29d60 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
29d70 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
29d80 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
29d90 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
29da0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
29db0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
29dc0 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
29dd0 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
29de0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
29df0 6f 72 64 65 72 20 73 74 72 69 6e 67 20 61 6e 64  order string and
29e00 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
29e10 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74       a pointer t
29e20 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
29e30 2a 0a 2a 2a 20 7b 48 31 33 38 32 37 7d 20 54 68  *.** {H13827} Th
29e40 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
29e50 6e 5f 74 79 70 65 28 53 2c 4e 29 5d 20 69 6e 74  n_type(S,N)] int
29e60 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
29e70 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f  *          one o
29e80 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c  f [SQLITE_NULL],
29e90 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
29ea0 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ], [SQLITE_FLOAT
29eb0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
29ec0 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72  SQLITE_TEXT], or
29ed0 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61   [SQLITE_BLOB] a
29ee0 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  s appropriate fo
29ef0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
29f00 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20  e Nth column in 
29f10 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
29f20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
29f30 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
29f40 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20    the [prepared 
29f50 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a  statement] S..**
29f60 0a 2a 2a 20 7b 48 31 33 38 33 30 7d 20 54 68 65  .** {H13830} The
29f70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
29f80 5f 76 61 6c 75 65 28 53 2c 4e 29 5d 20 69 6e 74  _value(S,N)] int
29f90 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
29fa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69  .**          poi
29fb0 6e 74 65 72 20 74 6f 20 61 6e 20 5b 75 6e 70 72  nter to an [unpr
29fc0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29fd0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
29fe0 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
29ff0 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
2a000 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
2a010 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2a020 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
2a030 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20    the [prepared 
2a040 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
2a050 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2a060 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2a070 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a080 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
2a090 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2a0a0 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
2a0b0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2a0c0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2a0d0 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
2a0e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2a0f0 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
2a100 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
2a110 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a120 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2a130 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2a140 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a150 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
2a160 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
2a170 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
2a180 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a190 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e   iCol);.const un
2a1a0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
2a1b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2a1c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a1d0 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
2a1e0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2a1f0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
2a200 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2a210 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2a220 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
2a230 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2a240 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
2a250 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
2a260 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
2a270 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2a280 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
2a290 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
2a2a0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2a2b0 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33  ment Object {H13
2a2c0 33 30 30 7d 20 3c 53 37 30 33 30 30 3e 3c 53 33  300} <S70300><S3
2a2d0 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0100>.**.** The 
2a2e0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2a2f0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
2a300 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
2a310 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2a320 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
2a330 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
2a340 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73  executed success
2a350 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65  fully or not exe
2a360 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68  cuted at all, th
2a370 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20  en.** SQLITE_OK 
2a380 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20  is returned. If 
2a390 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
2a3a0 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65   statement faile
2a3b0 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72  d then an.** [er
2a3c0 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78  ror code] or [ex
2a3d0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
2a3e0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
2a3f0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2a400 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
2a410 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
2a420 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ring the executi
2a430 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72  on of the.** [pr
2a440 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a450 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72 74 75  ].  If the virtu
2a460 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e  al machine has n
2a470 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  ot.** completed 
2a480 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74  execution when t
2a490 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63  his routine is c
2a4a0 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c  alled, that is l
2a4b0 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ike.** encounter
2a4c0 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  ing an error or 
2a4d0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  an [sqlite3_inte
2a4e0 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70  rrupt | interrup
2a4f0 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74  t]..** Incomplet
2a500 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65  e updates may be
2a510 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64   rolled back and
2a520 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61   transactions ca
2a530 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e  nceled,.** depen
2a540 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63  ding on the circ
2a550 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74  umstances, and t
2a560 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  he.** [error cod
2a570 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c  e] returned will
2a580 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   be [SQLITE_ABOR
2a590 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  T]..**.** INVARI
2a5a0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  ANTS:.**.** {H11
2a5b0 33 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  302} The [sqlite
2a5c0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69  3_finalize(S)] i
2a5d0 6e 74 65 72 66 61 63 65 20 64 65 73 74 72 6f 79  nterface destroy
2a5e0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2a5f0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
2a600 65 6d 65 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c  ement] S and rel
2a610 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20  eases all.**    
2a620 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64        memory and
2a630 20 66 69 6c 65 20 72 65 73 6f 75 72 63 65 73 20   file resources 
2a640 68 65 6c 64 20 62 79 20 74 68 61 74 20 6f 62 6a  held by that obj
2a650 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  ect..**.** {H113
2a660 30 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20  04} If the most 
2a670 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2a680 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2a690 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
2a6a0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
2a6b0 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
2a6c0 72 6e 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a  rned an error,.*
2a6d0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
2a6e0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2a6f0 65 28 53 29 5d 20 72 65 74 75 72 6e 73 20 74 68  e(S)] returns th
2a700 61 74 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a  at same error..*
2a710 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
2a720 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
2a730 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2a740 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2a750 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
2a760 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20  tatement Object 
2a770 7b 48 31 33 33 33 30 7d 20 3c 53 37 30 33 30 30  {H13330} <S70300
2a780 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
2a790 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63  te3_reset() func
2a7a0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
2a7b0 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61  o reset a [prepa
2a7c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2a7d0 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f  * object back to
2a7e0 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
2a7f0 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
2a800 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
2a810 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
2a820 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
2a830 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
2a840 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
2a850 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
2a860 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
2a870 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
2a880 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
2a890 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
2a8a0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
2a8b0 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
2a8c0 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
2a8d0 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 32 7d 20 54  **.** {H11332} T
2a8e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2a8f0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2a900 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
2a910 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a920 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61  S.**          ba
2a930 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
2a940 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
2a950 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33  am..**.** {H1133
2a960 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  4} If the most r
2a970 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2a980 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2a990 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
2a9a0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
2a9b0 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
2a9c0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
2a9d0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
2a9e0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ],.**          o
2a9f0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
2aa00 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
2aa10 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
2aa20 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20  led on S,.**    
2aa30 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69        then [sqli
2aa40 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
2aa50 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
2aa60 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 36  ]..**.** {H11336
2aa70 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  } If the most re
2aa80 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2aa90 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2aaa0 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
2aab0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
2aac0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
2aad0 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
2aae0 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  en.**          [
2aaf0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2ab00 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
2ab10 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
2ab20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  code]..**.** {H1
2ab30 31 33 33 38 7d 20 54 68 65 20 5b 73 71 6c 69 74  1338} The [sqlit
2ab40 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
2ab50 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
2ab60 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
2ab70 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  s.**          of
2ab80 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
2ab90 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
2aba0 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
2abb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
2abc0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2abd0 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
2abe0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2abf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
2ac00 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
2ac10 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48  SQL Functions {H
2ac20 31 36 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a  16100} <S20200>.
2ac30 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75  ** KEYWORDS: {fu
2ac40 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
2ac50 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59  routines}.** KEY
2ac60 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
2ac70 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2ac80 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59  function}.** KEY
2ac90 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
2aca0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2acb0 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
2acc0 20 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63 74   These two funct
2acd0 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65  ions (collective
2ace0 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e  ly known as "fun
2acf0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
2ad00 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65  outines").** are
2ad10 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c   used to add SQL
2ad20 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
2ad30 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72  gregates or to r
2ad40 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61  edefine the beha
2ad50 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74  vior.** of exist
2ad60 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
2ad70 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e  s or aggregates.
2ad80 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65    The only diffe
2ad90 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20 74 68  rence between th
2ada0 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68 61 74  e.** two is that
2adb0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
2adc0 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 6d 65 20  meter, the name 
2add0 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29 20  of the (scalar) 
2ade0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2adf0 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63  ggregate, is enc
2ae00 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f  oded in UTF-8 fo
2ae10 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2ae20 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20  _function() and 
2ae30 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71  UTF-16.** for sq
2ae40 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2ae50 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a  ction16()..**.**
2ae60 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
2ae70 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
2ae80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2ae90 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
2aea0 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
2aeb0 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
2aec0 49 66 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  If a single prog
2aed0 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ram uses more th
2aee0 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
2aef0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e  ** connection in
2af00 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53  ternally, then S
2af10 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
2af20 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 69 76  t be added indiv
2af30 69 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61  idually to.** ea
2af40 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
2af50 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  ection..**.** Th
2af60 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2af70 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
2af80 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
2af90 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
2afa0 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
2afb0 2e 20 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66  .  The length of
2afc0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
2afd0 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
2afe0 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a  s, exclusive of.
2aff0 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  ** the zero-term
2b000 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68  inator.  Note th
2b010 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67  at the name leng
2b020 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62  th limit is in b
2b030 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61  ytes, not.** cha
2b040 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74  racters.  Any at
2b050 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
2b060 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
2b070 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
2b080 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
2b090 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62  [SQLITE_ERROR] b
2b0a0 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
2b0b0 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70  *.** The third p
2b0c0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2b0d0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2b0e0 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
2b0f0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2b100 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
2b110 20 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74   If this paramet
2b120 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
2b130 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
2b140 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
2b150 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
2b160 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
2b170 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  uments..**.** Th
2b180 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2b190 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
2b1a0 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
2b1b0 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
2b1c0 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
2b1d0 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
2b1e0 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
2b1f0 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
2b200 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  Any SQL function
2b210 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2b220 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74  should be able t
2b230 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77  o work.** work w
2b240 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31  ith UTF-8, UTF-1
2b250 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65  6le, or UTF-16be
2b260 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c  .  But some impl
2b270 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
2b280 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63  be.** more effic
2b290 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e  ient with one en
2b2a0 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74  coding than anot
2b2b0 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f  her.  It is allo
2b2c0 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  wed to.** invoke
2b2d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2b2e0 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71  function() or sq
2b2f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2b300 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70  ction16() multip
2b310 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
2b320 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2b330 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66  on but with diff
2b340 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20  erent values of 
2b350 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65  eTextRep..** Whe
2b360 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
2b370 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
2b380 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2b390 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
2b3a0 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
2b3b0 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
2b3c0 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
2b3d0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
2b3e0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
2b3f0 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
2b400 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
2b410 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
2b420 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
2b430 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64  at text.** encod
2b440 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
2b450 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
2b460 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
2b470 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a  [SQLITE_ANY]..**
2b480 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61  .** The fifth pa
2b490 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
2b4a0 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
2b4b0 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
2b4c0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
2b4d0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
2b4e0 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
2b4f0 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
2b500 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
2b510 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ()]..**.** The s
2b520 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61  eventh, eighth a
2b530 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  nd ninth paramet
2b540 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
2b550 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
2b560 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
2b570 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
2b580 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
2b590 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
2b5a0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
2b5b0 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20  egate. A scalar 
2b5c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
2b5d0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
2b5e0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
2b5f0 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
2b600 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e   only, NULL poin
2b610 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70  ters should be p
2b620 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
2b630 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a  ep and xFinal.**
2b640 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20   parameters. An 
2b650 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
2b660 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
2b670 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
2b680 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
2b690 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
2b6a0 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73  L should be pass
2b6b0 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f  ed for xFunc. To
2b6c0 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
2b6d0 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
2b6e0 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
2b6f0 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20  , pass NULL for 
2b700 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
2b710 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  on callbacks..**
2b720 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74  .** It is permit
2b730 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
2b740 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2b750 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2b760 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
2b770 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
2b780 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
2b790 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
2b7a0 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
2b7b0 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
2b7c0 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
2b7d0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53  xt encodings.  S
2b7e0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
2b7f0 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
2b800 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  tion most closel
2b810 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
2b820 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
2b830 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
2b840 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  s used..**.** IN
2b850 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2b860 7b 48 31 36 31 30 33 7d 20 54 68 65 20 5b 73 71  {H16103} The [sq
2b870 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2b880 63 74 69 6f 6e 31 36 28 29 5d 20 69 6e 74 65 72  ction16()] inter
2b890 66 61 63 65 20 62 65 68 61 76 65 73 20 65 78 61  face behaves exa
2b8a0 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ctly.**         
2b8b0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 63   like [sqlite3_c
2b8c0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2b8d0 5d 20 69 6e 20 65 76 65 72 79 20 77 61 79 20 65  ] in every way e
2b8e0 78 63 65 70 74 20 74 68 61 74 20 69 74 0a 2a 2a  xcept that it.**
2b8f0 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 70            interp
2b900 72 65 74 73 20 74 68 65 20 7a 46 75 6e 63 74 69  rets the zFuncti
2b910 6f 6e 4e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  onName argument 
2b920 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  as zero-terminat
2b930 65 64 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20  ed UTF-16.**    
2b940 20 20 20 20 20 20 6e 61 74 69 76 65 20 62 79 74        native byt
2b950 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20  e order instead 
2b960 6f 66 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69  of as zero-termi
2b970 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a  nated UTF-8..**.
2b980 2a 2a 20 7b 48 31 36 31 30 36 7d 20 41 20 73 75  ** {H16106} A su
2b990 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
2b9a0 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ion of.**       
2b9b0 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
2b9c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2b9d0 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e  D,X,N,E,...)] in
2b9e0 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
2b9f0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  s.**          or
2ba00 20 72 65 70 6c 61 63 65 73 20 63 61 6c 6c 62 61   replaces callba
2ba10 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20  ck functions in 
2ba20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2ba30 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20  nnection] D.**  
2ba40 20 20 20 20 20 20 20 20 75 73 65 64 20 74 6f 20          used to 
2ba50 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
2ba60 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64  L function named
2ba70 20 58 20 77 69 74 68 20 4e 20 70 61 72 61 6d 65   X with N parame
2ba80 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ters.**         
2ba90 20 61 6e 64 20 68 61 76 69 6e 67 20 61 20 70 72   and having a pr
2baa0 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2bab0 6f 64 69 6e 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a  oding of E..**.*
2bac0 2a 20 7b 48 31 36 31 30 39 7d 20 41 20 73 75 63  * {H16109} A suc
2bad0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2bae0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2baf0 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
2bb00 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20  ,P,F,S,L)].**   
2bb10 20 20 20 20 20 20 20 72 65 70 6c 61 63 65 73 20         replaces 
2bb20 74 68 65 20 50 2c 20 46 2c 20 53 2c 20 61 6e 64  the P, F, S, and
2bb30 20 4c 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 61   L values from a
2bb40 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77  ny prior calls w
2bb50 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
2bb60 74 68 65 20 73 61 6d 65 20 44 2c 20 58 2c 20 4e  the same D, X, N
2bb70 2c 20 61 6e 64 20 45 20 76 61 6c 75 65 73 2e 0a  , and E values..
2bb80 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 32 7d 20 54  **.** {H16112} T
2bb90 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2bba0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2bbb0 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ...)] interface 
2bbc0 66 61 69 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20  fails with.**   
2bbd0 20 20 20 20 20 20 20 61 20 72 65 74 75 72 6e 20         a return 
2bbe0 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
2bbf0 45 52 52 4f 52 5d 20 69 66 20 74 68 65 20 53 51  ERROR] if the SQ
2bc00 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 20  L function name 
2bc10 58 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  X is.**         
2bc20 20 6c 6f 6e 67 65 72 20 74 68 61 6e 20 32 35 35   longer than 255
2bc30 20 62 79 74 65 73 20 65 78 63 6c 75 73 69 76 65   bytes exclusive
2bc40 20 6f 66 20 74 68 65 20 7a 65 72 6f 20 74 65 72   of the zero ter
2bc50 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b  minator..**.** {
2bc60 48 31 36 31 31 38 7d 20 45 69 74 68 65 72 20 46  H16118} Either F
2bc70 20 6d 75 73 74 20 62 65 20 4e 55 4c 4c 20 61 6e   must be NULL an
2bc80 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20 6e 6f  d S and L are no
2bc90 6e 2d 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 46  n-NULL or else F
2bca0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
2bcb0 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20 53 20 61  non-NULL and S a
2bcc0 6e 64 20 4c 20 61 72 65 20 4e 55 4c 4c 2c 20 6f  nd L are NULL, o
2bcd0 74 68 65 72 77 69 73 65 0a 2a 2a 20 20 20 20 20  therwise.**     
2bce0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72       [sqlite3_cr
2bcf0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2bd00 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20  X,N,E,P,F,S,L)] 
2bd10 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
2bd20 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ERROR]..**.** {H
2bd30 31 36 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  16121} The [sqli
2bd40 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2bd50 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65  ion(D,...)] inte
2bd60 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
2bd70 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
2bd80 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53  error code of [S
2bd90 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 66 20 74  QLITE_BUSY] if t
2bda0 68 65 72 65 20 65 78 69 73 74 20 5b 70 72 65 70  here exist [prep
2bdb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2bdc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73  .**          ass
2bdd0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
2bde0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2bdf0 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
2be00 7b 48 31 36 31 32 34 7d 20 54 68 65 20 5b 73 71  {H16124} The [sq
2be10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2be20 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29  ction(D,X,N,...)
2be30 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  ] interface fail
2be40 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20  s with an.**    
2be50 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65        error code
2be60 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f   of [SQLITE_ERRO
2be70 52 5d 20 69 66 20 70 61 72 61 6d 65 74 65 72 20  R] if parameter 
2be80 4e 20 28 73 70 65 63 69 66 79 69 6e 67 20 74 68  N (specifying th
2be90 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20  e number.**     
2bea0 20 20 20 20 20 6f 66 20 61 72 67 75 6d 65 6e 74       of argument
2beb0 73 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  s to the SQL fun
2bec0 63 74 69 6f 6e 20 62 65 69 6e 67 20 72 65 67 69  ction being regi
2bed0 73 74 65 72 65 64 29 20 69 73 20 6c 65 73 73 0a  stered) is less.
2bee0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 6e  **          than
2bef0 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
2bf00 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b  han 127..**.** {
2bf10 48 31 36 31 32 37 7d 20 57 68 65 6e 20 4e 20 69  H16127} When N i
2bf20 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
2bf30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2bf40 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2bf50 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  ,N,...)].**     
2bf60 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63       interface c
2bf70 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 73 20  auses callbacks 
2bf80 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f  to be invoked fo
2bf90 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  r the SQL functi
2bfa0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  on.**          n
2bfb0 61 6d 65 64 20 58 20 77 68 65 6e 20 74 68 65 20  amed X when the 
2bfc0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2bfd0 6e 74 73 20 74 6f 20 74 68 65 20 53 51 4c 20 66  nts to the SQL f
2bfe0 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20  unction is.**   
2bff0 20 20 20 20 20 20 20 65 78 61 63 74 6c 79 20 4e         exactly N
2c000 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 30 7d  ..**.** {H16130}
2c010 20 57 68 65 6e 20 4e 20 69 73 20 2d 31 2c 20 74   When N is -1, t
2c020 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2c030 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2c040 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  N,...)].**      
2c050 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61      interface ca
2c060 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 73 20 74  uses callbacks t
2c070 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72  o be invoked for
2c080 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2c090 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61  n.**          na
2c0a0 6d 65 64 20 58 20 77 69 74 68 20 61 6e 79 20 6e  med X with any n
2c0b0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2c0c0 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33  ts..**.** {H1613
2c0d0 33 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f  3} When calls to
2c0e0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2c0f0 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2c100 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
2c110 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70    specify multip
2c120 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2c130 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
2c140 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 20 20 20  unction X.**    
2c150 20 20 20 20 20 20 61 6e 64 20 77 68 65 6e 20 6f        and when o
2c160 6e 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ne implementatio
2c170 6e 20 68 61 73 20 4e 3e 3d 30 20 61 6e 64 20 74  n has N>=0 and t
2c180 68 65 20 6f 74 68 65 72 20 68 61 73 20 4e 3d 28  he other has N=(
2c190 2d 31 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  -1).**          
2c1a0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
2c1b0 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  on with a non-ze
2c1c0 72 6f 20 4e 20 69 73 20 70 72 65 66 65 72 72 65  ro N is preferre
2c1d0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 36  d..**.** {H16136
2c1e0 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  } When calls to 
2c1f0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2c200 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
2c210 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
2c220 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69     specify multi
2c230 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
2c240 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
2c250 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 0a  function X with.
2c260 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2c270 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66 20 61  same number of a
2c280 72 67 75 6d 65 6e 74 73 20 4e 20 62 75 74 20 77  rguments N but w
2c290 69 74 68 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a  ith different.**
2c2a0 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 69            encodi
2c2b0 6e 67 73 20 45 2c 20 74 68 65 6e 20 74 68 65 20  ngs E, then the 
2c2c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2c2d0 68 65 72 65 20 45 20 6d 61 74 63 68 65 73 20 74  here E matches t
2c2e0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  he.**          d
2c2f0 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
2c300 20 69 73 20 70 72 65 66 65 72 72 65 64 2e 0a 2a   is preferred..*
2c310 2a 0a 2a 2a 20 7b 48 31 36 31 33 39 7d 20 46 6f  *.** {H16139} Fo
2c320 72 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 53  r an aggregate S
2c330 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  QL function crea
2c340 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  ted using.**    
2c350 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
2c360 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2c370 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d  ,X,N,E,P,0,S,L)]
2c380 20 74 68 65 20 66 69 6e 61 6c 69 7a 65 72 0a 2a   the finalizer.*
2c390 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74  *          funct
2c3a0 69 6f 6e 20 4c 20 77 69 6c 6c 20 61 6c 77 61 79  ion L will alway
2c3b0 73 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 78 61  s be invoked exa
2c3c0 63 74 6c 79 20 6f 6e 63 65 20 69 66 20 74 68 65  ctly once if the
2c3d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 65  .**          ste
2c3e0 70 20 66 75 6e 63 74 69 6f 6e 20 53 20 69 73 20  p function S is 
2c3f0 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
2c400 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20  re times..**.** 
2c410 7b 48 31 36 31 34 32 7d 20 57 68 65 6e 20 53 51  {H16142} When SQ
2c420 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 65 69 74  Lite invokes eit
2c430 68 65 72 20 74 68 65 20 78 46 75 6e 63 20 6f 72  her the xFunc or
2c440 20 78 53 74 65 70 20 66 75 6e 63 74 69 6f 6e 20   xStep function 
2c450 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  of.**          a
2c460 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
2c470 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2c480 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 20  on or aggregate 
2c490 63 72 65 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  created.**      
2c4a0 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f      by [sqlite3_
2c4b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2c4c0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63  )] or [sqlite3_c
2c4d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2c4e0 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
2c4f0 20 74 68 65 6e 20 74 68 65 20 61 72 72 61 79 20   then the array 
2c500 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  of [sqlite3_valu
2c510 65 5d 20 6f 62 6a 65 63 74 73 20 70 61 73 73 65  e] objects passe
2c520 64 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  d as the.**     
2c530 20 20 20 20 20 74 68 69 72 64 20 70 61 72 61 6d       third param
2c540 65 74 65 72 20 61 72 65 20 61 6c 77 61 79 73 20  eter are always 
2c550 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2c560 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2c570 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
2c580 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2c590 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
2c5a0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
2c5b0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2c5c0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2c5d0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2c5e0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2c5f0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2c600 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2c610 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2c620 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2c630 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2c640 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2c650 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2c660 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2c670 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
2c680 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2c690 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71  function16(.  sq
2c6a0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
2c6b0 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69  st void *zFuncti
2c6c0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
2c6d0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
2c6e0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
2c6f0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
2c700 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2c710 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2c720 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2c730 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
2c740 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2c750 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2c760 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
2c770 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2c780 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
2c790 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
2c7a0 64 69 6e 67 73 20 7b 48 31 30 32 36 37 7d 20 3c  dings {H10267} <
2c7b0 53 35 30 32 30 30 3e 20 3c 48 31 36 31 30 30 3e  S50200> <H16100>
2c7c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2c7d0 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
2c7e0 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
2c7f0 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
2c800 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
2c810 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
2c820 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
2c830 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2c840 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a  TF8           1.
2c850 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2c860 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a  TF16LE        2.
2c870 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2c880 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a  TF16BE        3.
2c890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2c8a0 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
2c8b0 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
2c8c0 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
2c8d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
2c8e0 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
2c8f0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
2c900 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c  ate_function onl
2c910 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
2c920 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
2c930 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74  D  8    /* sqlit
2c940 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2c950 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a  ion only */../*.
2c960 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 73  ** CAPI3REF: Obs
2c970 6f 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e 73 0a  olete Functions.
2c980 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
2c990 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20 6e 6f  tions are all no
2c9a0 77 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49 6e 20  w obsolete.  In 
2c9b0 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
2c9c0 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
2c9d0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
2c9e0 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 77 65  h older code, we
2c9f0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73 75 70   continue to sup
2ca00 70 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20 66 75  port.** these fu
2ca10 6e 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65 76 65  nctions.  Howeve
2ca20 72 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70 6d 65  r, new developme
2ca30 6e 74 20 70 72 6f 6a 65 63 74 73 20 73 68 6f 75  nt projects shou
2ca40 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
2ca50 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
2ca60 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70  ctions.  To help
2ca70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c   encourage peopl
2ca80 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73  e to avoid.** us
2ca90 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69  ing these functi
2caa0 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20  ons, we are not 
2cab0 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f  going to tell yo
2cac0 75 20 77 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a  u want they do..
2cad0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  */.int sqlite3_a
2cae0 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
2caf0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2cb00 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  ;.int sqlite3_ex
2cb10 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
2cb20 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  mt*);.int sqlite
2cb30 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
2cb40 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
2cb50 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
2cb60 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  );.int sqlite3_g
2cb70 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
2cb80 69 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  id);.void sqlite
2cb90 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70  3_thread_cleanup
2cba0 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
2cbb0 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
2cbc0 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73  (void(*)(void*,s
2cbd0 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74  qlite3_int64,int
2cbe0 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  ),void*,sqlite3_
2cbf0 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int64);../*.** C
2cc00 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
2cc10 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  ng SQL Function 
2cc20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73  Parameter Values
2cc30 20 7b 48 31 35 31 30 30 7d 20 3c 53 32 30 32 30   {H15100} <S2020
2cc40 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  0>.**.** The C-l
2cc50 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
2cc60 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
2cc70 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
2cc80 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
2cc90 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
2cca0 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
2ccb0 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
2ccc0 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
2ccd0 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
2cce0 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
2ccf0 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
2cd00 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
2cd10 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
2cd20 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
2cd30 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
2cd40 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2cd50 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
2cd60 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2cd70 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
2cd80 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
2cd90 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
2cda0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2cdb0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
2cdc0 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61  s..** The 4th pa
2cdd0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
2cde0 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
2cdf0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
2ce00 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
2ce10 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2ce20 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
2ce30 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
2ce40 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2ce50 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
2ce60 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
2ce70 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
2ce80 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2ce90 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
2cea0 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
2ceb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2cec0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
2ced0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2cee0 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
2cef0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2cf00 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2cf10 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
2cf20 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
2cf30 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
2cf40 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2cf50 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
2cf60 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
2cf70 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
2cf80 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  r..**.** These r
2cf90 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
2cfa0 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
2cfb0 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
2cfc0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2cfd0 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
2cfe0 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  t  these routine
2cff0 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
2d000 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2d010 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2d020 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
2d030 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
2d040 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
2d050 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
2d060 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
2d070 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2d080 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
2d090 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
2d0a0 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
2d0b0 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
2d0c0 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
2d0d0 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
2d0e0 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ne.  The.** sqli
2d0f0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2d100 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
2d110 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
2d120 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
2d130 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
2d140 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
2d150 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
2d160 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
2d170 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
2d180 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
2d190 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
2d1a0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
2d1b0 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
2d1c0 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
2d1d0 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
2d1e0 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
2d1f0 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
2d200 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
2d210 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
2d220 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
2d230 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
2d240 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
2d250 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
2d260 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
2d270 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
2d280 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
2d290 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
2d2a0 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
2d2b0 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
2d2c0 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
2d2d0 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
2d2e0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
2d2f0 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
2d300 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
2d310 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
2d320 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
2d330 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
2d340 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  rned..**.** Plea
2d350 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
2d360 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
2d370 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
2d380 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65   pointer returne
2d390 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
2d3a0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
2d3b0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2d3c0 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
2d3d0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2d3e0 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
2d3f0 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
2d400 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
2d410 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2d420 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
2d430 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2d440 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
2d450 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
2d460 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
2d470 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
2d480 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ]..**.** These r
2d490 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
2d4a0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
2d4b0 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
2d4c0 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
2d4d0 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
2d4e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2d4f0 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
2d500 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2d510 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30  TS:.**.** {H1510
2d520 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
2d530 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 69  value_blob(V)] i
2d540 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2d550 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2d560 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2d570 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2d580 63 74 20 56 20 69 6e 74 6f 20 61 20 42 4c 4f 42  ct V into a BLOB
2d590 20 61 6e 64 20 74 68 65 6e 0a 2a 2a 20 20 20 20   and then.**    
2d5a0 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
2d5b0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
2d5c0 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a  onverted value..
2d5d0 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 36 7d 20 54  **.** {H15106} T
2d5e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2d5f0 65 5f 62 79 74 65 73 28 56 29 5d 20 69 6e 74 65  e_bytes(V)] inte
2d600 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2d610 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
2d620 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2d630 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
2d640 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f  ing (exclusive o
2d650 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2d660 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f    zero terminato
2d670 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29  r on the string)
2d680 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
2d690 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
2d6a0 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e        most recen
2d6b0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2d6c0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29  e3_value_blob(V)
2d6d0 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
2d6e0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d6f0 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20  text(V)]..**.** 
2d700 7b 48 31 35 31 30 39 7d 20 54 68 65 20 5b 73 71  {H15109} The [sq
2d710 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2d720 73 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63  s16(V)] interfac
2d730 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2d740 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
2d750 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2d760 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69   string (exclusi
2d770 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ve of the.**    
2d780 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69        zero termi
2d790 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72  nator on the str
2d7a0 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65  ing) that was re
2d7b0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
2d7c0 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72            most r
2d7d0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2d7e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2d7f0 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20 20 20 20  t16(V)],.**     
2d800 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61       [sqlite3_va
2d810 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d  lue_text16be(V)]
2d820 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  , or [sqlite3_va
2d830 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d  lue_text16le(V)]
2d840 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 32 7d  ..**.** {H15112}
2d850 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2d860 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29 5d 20 69  lue_double(V)] i
2d870 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2d880 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2d890 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2d8a0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2d8b0 63 74 20 56 20 69 6e 74 6f 20 61 20 66 6c 6f 61  ct V into a floa
2d8c0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2d8d0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
2d8e0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
2d8f0 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a  of that value..*
2d900 2a 0a 2a 2a 20 7b 48 31 35 31 31 35 7d 20 54 68  *.** {H15115} Th
2d910 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2d920 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65 72 66 61  _int(V)] interfa
2d930 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2d940 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f  **          [pro
2d950 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2d960 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
2d970 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67  nto a 64-bit sig
2d980 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a  ned integer and.
2d990 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2d9a0 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32  rns the lower 32
2d9b0 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e   bits of that in
2d9c0 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  teger..**.** {H1
2d9d0 35 31 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74  5118} The [sqlit
2d9e0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 56  e3_value_int64(V
2d9f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2da00 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2da10 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
2da20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2da30 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
2da40 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2da50 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20  teger and.**    
2da60 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
2da70 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74  copy of that int
2da80 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  eger..**.** {H15
2da90 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  121} The [sqlite
2daa0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d  3_value_text(V)]
2dab0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2dac0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2dad0 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2dae0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2daf0 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65  ject V into a ze
2db00 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
2db10 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  F-8.**          
2db20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2db30 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2db40 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
2db50 2a 2a 20 7b 48 31 35 31 32 34 7d 20 54 68 65 20  ** {H15124} The 
2db60 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2db70 65 78 74 31 36 28 56 29 5d 20 69 6e 74 65 72 66  ext16(V)] interf
2db80 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2db90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2dba0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2dbb0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
2dbc0 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
2dbd0 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a  inated 2-byte.**
2dbe0 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65            aligne
2dbf0 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  d UTF-16 native 
2dc00 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
2dc10 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
2dc20 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
2dc30 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
2dc40 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32  ng..**.** {H1512
2dc50 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
2dc60 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56  value_text16be(V
2dc70 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2dc80 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2dc90 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
2dca0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2dcb0 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
2dcc0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2dcd0 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20  2-byte.**       
2dce0 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31     aligned UTF-1
2dcf0 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20  6 big-endian.** 
2dd00 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2dd10 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
2dd20 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
2dd30 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ring..**.** {H15
2dd40 31 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  130} The [sqlite
2dd50 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
2dd60 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2dd70 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2dd80 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
2dd90 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2dda0 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2ddb0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2ddc0 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
2ddd0 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
2dde0 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  -16 little-endia
2ddf0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  n.**          st
2de00 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2de10 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2de20 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
2de30 20 7b 48 31 35 31 33 33 7d 20 54 68 65 20 5b 73   {H15133} The [s
2de40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
2de50 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(V)] interface 
2de60 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
2de70 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49      one of [SQLI
2de80 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_NULL], [SQLIT
2de90 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c  E_INTEGER], [SQL
2dea0 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20  ITE_FLOAT],.**  
2deb0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
2dec0 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  TEXT], or [SQLIT
2ded0 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f  E_BLOB] as appro
2dee0 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20  priate for.**   
2def0 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69         the [sqli
2df00 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2df10 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  t V..**.** {H151
2df20 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  36} The [sqlite3
2df30 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
2df40 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  ype(V)] interfac
2df50 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 20 20  e converts.**   
2df60 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 6f 74         the [prot
2df70 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2df80 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
2df90 74 6f 20 65 69 74 68 65 72 20 61 6e 20 69 6e 74  to either an int
2dfa0 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20 20 20 20  eger or.**      
2dfb0 20 20 20 20 61 20 66 6c 6f 61 74 69 6e 67 20 70      a floating p
2dfc0 6f 69 6e 74 20 76 61 6c 75 65 20 69 66 20 69 74  oint value if it
2dfd0 20 63 61 6e 20 64 6f 20 73 6f 20 77 69 74 68 6f   can do so witho
2dfe0 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a 20 20 20  ut loss of.**   
2dff0 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61 74 69         informati
2e000 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  on, and returns 
2e010 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e  one of [SQLITE_N
2e020 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ULL],.**        
2e030 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45    [SQLITE_INTEGE
2e040 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  R], [SQLITE_FLOA
2e050 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
2e060 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
2e070 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20    [SQLITE_BLOB] 
2e080 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  as appropriate f
2e090 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
2e0a0 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
2e0b0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2e0c0 65 63 74 20 56 20 61 66 74 65 72 20 74 68 65 20  ect V after the 
2e0d0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74 74 65 6d  conversion attem
2e0e0 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  pt..*/.const voi
2e0f0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2e100 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
2e110 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2e120 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
2e130 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2e140 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2e150 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
2e160 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
2e170 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
2e180 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
2e190 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2e1a0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
2e1b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
2e1c0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
2e1d0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
2e1e0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2e1f0 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
2e200 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
2e210 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
2e220 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
2e230 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
2e240 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
2e250 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
2e260 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2e270 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
2e280 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2e290 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2e2a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2e2b0 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
2e2c0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2e2d0 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
2e2e0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2e2f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
2e300 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
2e310 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
2e320 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
2e330 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
2e340 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
2e350 7b 48 31 36 32 31 30 7d 20 3c 53 32 30 32 30 30  {H16210} <S20200
2e360 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c  >.**.** The impl
2e370 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67  ementation of ag
2e380 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
2e390 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72  tions use this r
2e3a0 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
2e3b0 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72  te.** a structur
2e3c0 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  e for storing th
2e3d0 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
2e3e0 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   The first time 
2e3f0 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
2e400 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2e410 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
2e420 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69  d for a.** parti
2e430 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c  cular aggregate,
2e440 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65   SQLite allocate
2e450 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f  s nBytes of memo
2e460 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
2e470 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61  hat.** memory, a
2e480 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
2e490 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73  nter to it. On s
2e4a0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
2e4b0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
2e4c0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2e4d0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
2e4e0 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
2e4f0 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64  ate function ind
2e500 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ex,.** the same 
2e510 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
2e520 65 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  ed. The implemen
2e530 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 61 67  tation of the ag
2e540 67 72 65 67 61 74 65 20 63 61 6e 20 75 73 65 0a  gregate can use.
2e550 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 65 64 20  ** the returned 
2e560 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75  buffer to accumu
2e570 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  late data..**.**
2e580 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
2e590 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
2e5a0 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72  allocated buffer
2e5b0 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
2e5c0 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e  ate.** query con
2e5d0 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
2e5e0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2e5f0 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f  r should be a co
2e600 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
2e610 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
2e620 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
2e630 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
2e640 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2e650 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
2e660 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
2e670 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
2e680 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2e690 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
2e6a0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
2e6b0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
2e6c0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
2e6d0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
2e6e0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2e6f0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
2e700 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2e710 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 31 7d 20  .**.** {H16211} 
2e720 54 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61  The first invoca
2e730 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
2e740 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2e750 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20  xt(C,N)] for.** 
2e760 20 20 20 20 20 20 20 20 20 61 20 70 61 72 74 69           a parti
2e770 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f  cular instance o
2e780 66 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 66  f an aggregate f
2e790 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61 20 70  unction (for a p
2e7a0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20  articular.**    
2e7b0 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 29        context C)
2e7c0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
2e7d0 6f 20 61 6c 6c 6f 63 61 74 65 20 4e 20 62 79 74  o allocate N byt
2e7e0 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  es of memory,.**
2e7f0 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
2e800 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
2e810 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72  return a pointer
2e820 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   to the allocate
2e830 64 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  d memory..**.** 
2e840 7b 48 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65  {H16213} If a me
2e850 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2e860 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
2e870 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
2e880 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
2e890 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d  te_context(C,N)]
2e8a0 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   then the functi
2e8b0 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  on returns 0..**
2e8c0 0a 2a 2a 20 7b 48 31 36 32 31 35 7d 20 53 65 63  .** {H16215} Sec
2e8d0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2e8e0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  nt invocations o
2e8f0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  f.**          [s
2e900 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2e910 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66  _context(C,N)] f
2e920 6f 72 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74  or the same cont
2e930 65 78 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a  ext pointer C.**
2e940 20 20 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65            ignore
2e950 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
2e960 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f   and return a po
2e970 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d  inter to the sam
2e980 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c  e.**          bl
2e990 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65  ock of memory re
2e9a0 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 66 69  turned by the fi
2e9b0 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a  rst invocation..
2e9c0 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 37 7d 20 54  **.** {H16217} T
2e9d0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
2e9e0 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ted by [sqlite3_
2e9f0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2ea00 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20  t(C,N)] is.**   
2ea10 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63         automatic
2ea20 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68  ally freed on th
2ea30 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b  e next call to [
2ea40 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2ea50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
2ea60 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2ea70 65 28 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72  e()] for the [pr
2ea80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ea90 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20  ] containing.** 
2eaa0 20 20 20 20 20 20 20 20 20 74 68 65 20 61 67 67           the agg
2eab0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
2eac0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2ead0 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f  context C..*/.vo
2eae0 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
2eaf0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
2eb00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2eb10 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
2eb20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
2eb30 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
2eb40 74 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c  tions {H16240} <
2eb50 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
2eb60 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
2eb70 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
2eb80 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2eb90 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
2eba0 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
2ebb0 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
2ebc0 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
2ebd0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
2ebe0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2ebf0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
2ec00 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2ec10 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2ec20 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
2ec30 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
2ec40 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
2ec50 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
2ec60 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a  function. {END}.
2ec70 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2ec80 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
2ec90 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2eca0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2ecb0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2ecc0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2ecd0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2ece0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2ecf0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 34 33 7d  :.**.** {H16243}
2ed00 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 73   The [sqlite3_us
2ed10 65 72 5f 64 61 74 61 28 43 29 5d 20 69 6e 74 65  er_data(C)] inte
2ed20 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2ed30 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20  copy of the.**  
2ed40 20 20 20 20 20 20 20 20 50 20 70 6f 69 6e 74 65          P pointe
2ed50 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  r from the [sqli
2ed60 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ed70 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  ion(D,X,N,E,P,F,
2ed80 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,L)].**        
2ed90 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72    or [sqlite3_cr
2eda0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2edb0 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
2edc0 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20  ] call that.**  
2edd0 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
2ede0 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ed the SQL funct
2edf0 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77  ion associated w
2ee00 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ith [sqlite3_con
2ee10 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64  text] C..*/.void
2ee20 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   *sqlite3_user_d
2ee30 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
2ee40 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
2ee50 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2ee60 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20   Connection For 
2ee70 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 35  Functions {H1625
2ee80 30 7d 20 3c 53 36 30 36 30 30 3e 3c 53 32 30 32  0} <S60600><S202
2ee90 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
2eea0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2eeb0 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
2eec0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
2eed0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
2eee0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
2eef0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2ef00 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
2ef10 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
2ef20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2ef30 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
2ef40 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2ef50 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2ef60 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
2ef70 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
2ef80 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
2ef90 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
2efa0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2efb0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2efc0 2a 20 7b 48 31 36 32 35 33 7d 20 54 68 65 20 5b  * {H16253} The [
2efd0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
2efe0 64 62 5f 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e  db_handle(C)] in
2eff0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2f000 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
2f010 20 20 20 20 20 20 20 20 20 20 44 20 70 6f 69 6e            D poin
2f020 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ter from the [sq
2f030 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2f040 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
2f050 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20  F,S,L)].**      
2f060 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
2f070 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2f080 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  6(D,X,N,E,P,F,S,
2f090 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a  L)] call that.**
2f0a0 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
2f0b0 65 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e  ered the SQL fun
2f0c0 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64  ction associated
2f0d0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63   with [sqlite3_c
2f0e0 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71  ontext] C..*/.sq
2f0f0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
2f100 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
2f110 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2f120 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2f130 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
2f140 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b 48 31  xiliary Data {H1
2f150 36 32 37 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  6270} <S20200>.*
2f160 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
2f170 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
2f180 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
2f190 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
2f1a0 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
2f1b0 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
2f1c0 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
2f1d0 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
2f1e0 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
2f1f0 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
2f200 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
2f210 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
2f220 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
2f230 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
2f240 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
2f250 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
2f260 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
2f270 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
2f280 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65  . This may.** be
2f290 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70   used, for examp
2f2a0 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67  le, to add a reg
2f2b0 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
2f2c0 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a  matching scalar.
2f2d0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
2f2e0 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
2f2f0 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
2f300 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73   expression is s
2f310 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
2f320 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
2f330 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
2f340 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
2f350 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
2f360 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
2f370 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
2f380 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
2f390 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
2f3a0 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
2f3b0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
2f3c0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
2f3d0 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
2f3e0 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
2f3f0 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
2f400 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
2f410 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
2f420 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  ocation..**.** T
2f430 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
2f440 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
2f450 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2f460 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
2f470 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
2f480 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
2f490 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
2f4a0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68  function with th
2f4b0 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  e Nth argument.*
2f4c0 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61  * value to the a
2f4d0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2f4e0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20  ed function. If 
2f4f0 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  no metadata has 
2f500 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65  been ever.** bee
2f510 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74  n set for the Nt
2f520 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  h argument of th
2f530 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
2f540 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
2f550 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
2f560 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68  parameter has ch
2f570 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
2f580 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
2f590 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  t,.** then sqlit
2f5a0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2f5b0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
2f5c0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
2f5d0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
2f5e0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
2f5f0 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74  ce saves the met
2f600 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  adata.** pointed
2f610 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
2f620 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
2f630 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
2f640 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
2f650 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
2f660 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2f670 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65  ction.  Subseque
2f680 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
2f690 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2f6a0 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72  ta() might retur
2f6b0 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20  n this data, if 
2f6c0 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65  it has.** not be
2f6d0 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  en destroyed..**
2f6e0 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55   If it is not NU
2f6f0 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
2f700 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
2f710 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  uctor.** functio
2f720 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34  n given by the 4
2f730 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2f740 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2f750 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20  ata() on.** the 
2f760 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68  metadata when th
2f770 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2f780 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
2f790 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72  er changes.** or
2f7a0 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   when the SQL st
2f7b0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65  atement complete
2f7c0 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  s, whichever com
2f7d0 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
2f7e0 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
2f7f0 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72  o call the destr
2f800 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d  uctor and drop m
2f810 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a  etadata on any.*
2f820 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61  * parameter of a
2f830 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61  ny function at a
2f840 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e  ny time.  The on
2f850 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20  ly guarantee is 
2f860 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74  that.** the dest
2f870 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63  ructor will be c
2f880 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65  alled before the
2f890 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f   metadata is dro
2f8a0 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70  pped..**.** In p
2f8b0 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74  ractice, metadat
2f8c0 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62  a is preserved b
2f8d0 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20  etween function 
2f8e0 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70  calls for.** exp
2f8f0 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72  ressions that ar
2f900 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f  e constant at co
2f910 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73  mpile time. This
2f920 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61   includes litera
2f930 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
2f940 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a  SQL variables..*
2f950 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2f960 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
2f970 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2f980 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2f990 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
2f9a0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2f9b0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2f9c0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 32  S:.**.** {H16272
2f9d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67  } The [sqlite3_g
2f9e0 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d  et_auxdata(C,N)]
2f9f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2fa00 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
2fa10 20 20 20 20 20 20 20 20 20 74 6f 20 6d 65 74 61           to meta
2fa20 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
2fa30 77 69 74 68 20 74 68 65 20 4e 74 68 20 70 61 72  with the Nth par
2fa40 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51  ameter of the SQ
2fa50 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  L function.**   
2fa60 20 20 20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e         whose con
2fa70 74 65 78 74 20 69 73 20 43 2c 20 6f 72 20 4e 55  text is C, or NU
2fa80 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e  LL if there is n
2fa90 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  o metadata assoc
2faa0 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  iated.**        
2fab0 20 20 77 69 74 68 20 74 68 61 74 20 70 61 72 61    with that para
2fac0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  meter..**.** {H1
2fad0 36 32 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  6274} The [sqlit
2fae0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
2faf0 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,N,P,D)] interfa
2fb00 63 65 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74  ce assigns a met
2fb10 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20  adata.**        
2fb20 20 20 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74    pointer P to t
2fb30 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72  he Nth parameter
2fb40 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
2fb50 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 78  tion with contex
2fb60 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  t C..**.** {H162
2fb70 37 36 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  76} SQLite will 
2fb80 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
2fb90 75 63 74 6f 72 20 44 20 77 69 74 68 20 61 20 73  uctor D with a s
2fba0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ingle argument.*
2fbb0 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 63 68  *          which
2fbc0 20 69 73 20 74 68 65 20 6d 65 74 61 64 61 74 61   is the metadata
2fbd0 20 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f   pointer P follo
2fbe0 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  wing a call to.*
2fbf0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2fc00 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2fc10 43 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53  C,N,P,D)] when S
2fc20 51 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20  QLite ceases to 
2fc30 68 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  hold.**         
2fc40 20 74 68 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a   the metadata..*
2fc50 2a 0a 2a 2a 20 7b 48 31 36 32 37 37 7d 20 53 51  *.** {H16277} SQ
2fc60 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68  Lite ceases to h
2fc70 6f 6c 64 20 6d 65 74 61 64 61 74 61 20 66 6f 72  old metadata for
2fc80 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
2fc90 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
2fca0 20 20 20 20 20 20 20 77 68 65 6e 20 74 68 65 20         when the 
2fcb0 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 70 61  value of that pa
2fcc0 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2e  rameter changes.
2fcd0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 38 7d 20  .**.** {H16278} 
2fce0 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65  When [sqlite3_se
2fcf0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
2fd00 44 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  D)] is invoked, 
2fd10 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
2fd20 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 63 61  *          is ca
2fd30 6c 6c 65 64 20 66 6f 72 20 61 6e 79 20 70 72 69  lled for any pri
2fd40 6f 72 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  or metadata asso
2fd50 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2fd60 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  same function.**
2fd70 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78            contex
2fd80 74 20 43 20 61 6e 64 20 70 61 72 61 6d 65 74 65  t C and paramete
2fd90 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  r N..**.** {H162
2fda0 37 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  79} SQLite will 
2fdb0 63 61 6c 6c 20 64 65 73 74 72 75 63 74 6f 72 73  call destructors
2fdc0 20 66 6f 72 20 61 6e 79 20 6d 65 74 61 64 61 74   for any metadat
2fdd0 61 20 69 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a  a it is holding.
2fde0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 61  **          in a
2fdf0 20 70 61 72 74 69 63 75 6c 61 72 20 5b 70 72 65   particular [pre
2fe00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2fe10 20 53 20 77 68 65 6e 20 65 69 74 68 65 72 0a 2a   S when either.*
2fe20 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2fe30 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 6f 72  te3_reset(S)] or
2fe40 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2fe50 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64  ze(S)] is called
2fe60 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
2fe70 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
2fe80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2fe90 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71   int N);.void sq
2fea0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2feb0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
2fec0 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a  t*, int N, void*
2fed0 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a  , void (*)(void*
2fee0 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ));.../*.** CAPI
2fef0 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20  3REF: Constants 
2ff00 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c  Defining Special
2ff10 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61   Destructor Beha
2ff20 76 69 6f 72 20 7b 48 31 30 32 38 30 7d 20 3c 53  vior {H10280} <S
2ff30 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30100>.**.** The
2ff40 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
2ff50 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
2ff60 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
2ff70 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
2ff80 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
2ff90 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
2ffa0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
2ffb0 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49  sult_blob()].  I
2ffc0 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
2ffd0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
2ffe0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
2fff0 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
30000 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
30010 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
30020 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
30030 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
30040 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
30050 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a  estroyed.  The.*
30060 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  * SQLITE_TRANSIE
30070 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74  NT value means t
30080 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
30090 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e  will likely chan
300a0 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61  ge in.** the nea
300b0 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61  r future and tha
300c0 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20  t SQLite should 
300d0 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69  make its own pri
300e0 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  vate copy of.** 
300f0 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f  the content befo
30100 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
30110 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20  .** The typedef 
30120 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20  is necessary to 
30130 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62  work around prob
30140 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a  lems in certain.
30150 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73  ** C++ compilers
30160 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32  .  See ticket #2
30170 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  191..*/.typedef 
30180 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64  void (*sqlite3_d
30190 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28  estructor_type)(
301a0 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20  void*);.#define 
301b0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20  SQLITE_STATIC   
301c0 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
301d0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a  tructor_type)0).
301e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
301f0 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c  RANSIENT   ((sql
30200 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
30210 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20  type)-1)../*.** 
30220 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e  CAPI3REF: Settin
30230 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20  g The Result Of 
30240 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  An SQL Function 
30250 7b 48 31 36 34 30 30 7d 20 3c 53 32 30 32 30 30  {H16400} <S20200
30260 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
30270 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
30280 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
30290 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
302a0 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
302b0 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
302c0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
302d0 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
302e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
302f0 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
30300 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30310 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
30320 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
30330 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
30340 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
30350 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
30360 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
30370 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
30380 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
30390 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
303a0 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
303b0 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
303c0 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
303d0 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
303e0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
303f0 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
30400 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
30410 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
30420 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
30430 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  _blob() interfac
30440 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
30450 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
30460 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
30470 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
30480 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63  the BLOB whose c
30490 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65  ontent is pointe
304a0 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73  d.** to by the s
304b0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
304c0 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62  and which is N b
304d0 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20  ytes long where 
304e0 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  N is the.** thir
304f0 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
30500 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
30510 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
30520 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20   interfaces set 
30530 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
30540 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
30550 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
30560 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63  n to be a BLOB c
30570 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65  ontaining all ze
30580 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20  ro.** bytes and 
30590 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c  N bytes in size,
305a0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
305b0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64  value of the 2nd
305c0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
305d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
305e0 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e  sult_double() in
305f0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
30600 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
30610 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
30620 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
30630 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67  to be a floating
30640 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65   point value spe
30650 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73  cified.** by its
30660 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
30670 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
30680 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
30690 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
306a0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
306b0 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
306c0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
306d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
306e0 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
306f0 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  on..** SQLite us
30700 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f  es the string po
30710 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a  inted to by the.
30720 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ** 2nd parameter
30730 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75   of sqlite3_resu
30740 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
30750 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30760 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65  or16().** as the
30770 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
30780 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69  r message.  SQLi
30790 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
307a0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
307b0 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  ge string from s
307c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
307d0 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20  ror() as UTF-8. 
307e0 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
307f0 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
30800 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
30810 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
30820 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
30830 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
30840 20 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70    If the third p
30850 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
30860 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30870 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
30880 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
30890 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
308a0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
308b0 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
308c0 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
308d0 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
308e0 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
308f0 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  cter..** If the 
30900 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
30910 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
30920 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
30930 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
30940 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
30950 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
30960 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
30970 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
30980 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
30990 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
309a0 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
309b0 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54  or message..** T
309c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
309d0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
309e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
309f0 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
30a00 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
30a10 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
30a20 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
30a30 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
30a40 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
30a50 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
30a60 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
30a70 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
30a80 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
30a90 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
30aa0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65  out harm..** The
30ab0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30ac0 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
30ad0 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
30ae0 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
30af0 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
30b00 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
30b10 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
30b20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64 65  function.  By de
30b30 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72  fault,.** the er
30b40 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49  ror code is SQLI
30b50 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73 75 62  TE_ERROR.  A sub
30b60 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
30b70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
30b80 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
30b90 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
30ba0 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
30bb0 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
30bc0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
30bd0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
30be0 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69  esult_toobig() i
30bf0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
30c00 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
30c10 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
30c20 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
30c30 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
30c40 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  to long to repre
30c50 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  sent..**.** The 
30c60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
30c70 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
30c80 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
30c90 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
30ca0 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74  .** indicating t
30cb0 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  hat a memory all
30cc0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
30cd0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
30ce0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
30cf0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
30d00 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
30d10 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
30d20 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
30d30 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
30d40 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
30d50 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
30d60 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
30d70 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
30d80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30d90 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  int64() interfac
30da0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
30db0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
30dc0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
30dd0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
30de0 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20  o be the 64-bit 
30df0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
30e00 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
30e10 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
30e20 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  t..**.** The sql
30e30 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
30e40 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
30e50 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
30e60 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
30e70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
30e80 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
30e90 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
30ea0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
30eb0 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
30ec0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a  esult_text16(),.
30ed0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
30ee0 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e  t_text16le(), an
30ef0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
30f00 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65  _text16be() inte
30f10 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68  rfaces.** set th
30f20 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
30f30 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
30f40 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
30f50 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65  on to be.** a te
30f60 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20  xt string which 
30f70 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
30f80 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20  s UTF-8, UTF-16 
30f90 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
30fa0 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  r,.** UTF-16 lit
30fb0 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle endian, or U
30fc0 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e  TF-16 big endian
30fd0 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
30fe0 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  ** SQLite takes 
30ff0 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20  the text result 
31000 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61  from the applica
31010 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  tion from.** the
31020 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
31030 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  f the sqlite3_re
31040 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
31050 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65  faces..** If the
31060 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
31070 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
31080 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
31090 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61  faces.** is nega
310a0 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74  tive, then SQLit
310b0 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74  e takes result t
310c0 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  ext from the 2nd
310d0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68   parameter.** th
310e0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
310f0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
31100 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
31110 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
31120 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31130 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
31140 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
31150 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
31160 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
31170 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
31180 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
31190 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
311a0 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
311b0 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
311c0 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
311d0 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a  nction result..*
311e0 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72  * If the 4th par
311f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
31200 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31210 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
31220 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
31230 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e  lt_blob is a non
31240 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
31250 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73  hen SQLite calls
31260 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f   that.** functio
31270 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63  n as the destruc
31280 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20  tor on the text 
31290 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77  or BLOB result w
312a0 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69  hen it has.** fi
312b0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
312c0 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20  t result..** If 
312d0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
312e0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
312f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
31300 74 65 72 66 61 63 65 73 20 6f 72 0a 2a 2a 20 73  terfaces or.** s
31310 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
31320 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
31330 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
31340 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53  E_STATIC, then S
31350 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73  QLite.** assumes
31360 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f   that the text o
31370 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73  r BLOB result is
31380 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61   in constant spa
31390 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a  ce and does not.
313a0 2a 2a 20 63 6f 70 79 20 74 68 65 20 69 74 20 6f  ** copy the it o
313b0 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
313c0 74 6f 72 20 77 68 65 6e 20 69 74 20 68 61 73 20  tor when it has 
313d0 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
313e0 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  hat result..** I
313f0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
31400 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
31410 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
31420 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
31430 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31440 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
31450 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
31460 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
31470 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
31480 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
31490 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
314a0 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
314b0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
314c0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
314d0 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
314e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
314f0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
31500 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
31510 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
31520 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
31530 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
31540 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
31550 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
31560 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
31570 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
31580 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
31590 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20  ameter.  The.** 
315a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
315b0 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
315c0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
315d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
315e0 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
315f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
31600 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e  ue] specified in
31610 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d   the parameter m
31620 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  ay change or.** 
31630 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61  be deallocated a
31640 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73  fter sqlite3_res
31650 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75  ult_value() retu
31660 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d  rns without harm
31670 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74 65  ..** A [protecte
31680 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
31690 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61   object may alwa
316a0 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65  ys be used where
316b0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
316c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
316d0 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71  e] object is req
316e0 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72  uired, so either
316f0 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c  .** kind of [sql
31700 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
31710 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77  ct can be used w
31720 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61  ith this interfa
31730 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ce..**.** If the
31740 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
31750 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68  called from with
31760 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74  in the different
31770 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20   thread.** than 
31780 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69  the one containi
31790 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ng the applicati
317a0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
317b0 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65  ion that receive
317c0 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  d.** the [sqlite
317d0 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74  3_context] point
317e0 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  er, the results 
317f0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
31800 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
31810 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 33 7d 20  .**.** {H16403} 
31820 54 68 65 20 64 65 66 61 75 6c 74 20 72 65 74 75  The default retu
31830 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e  rn value from an
31840 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  y SQL function i
31850 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  s NULL..**.** {H
31860 31 36 34 30 36 7d 20 54 68 65 20 5b 73 71 6c 69  16406} The [sqli
31870 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
31880 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
31890 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
318a0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
318b0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
318c0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 20 42  tion C to be a B
318d0 4c 4f 42 20 74 68 61 74 20 69 73 20 4e 20 62 79  LOB that is N by
318e0 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tes.**          
318f0 69 6e 20 6c 65 6e 67 74 68 20 61 6e 64 20 77 69  in length and wi
31900 74 68 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  th content point
31910 65 64 20 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a  ed to by V..**.*
31920 2a 20 7b 48 31 36 34 30 39 7d 20 54 68 65 20 5b  * {H16409} The [
31930 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
31940 6f 75 62 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65  ouble(C,V)] inte
31950 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
31960 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
31970 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
31980 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
31990 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
319a0 74 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a  t value V..**.**
319b0 20 7b 48 31 36 34 31 32 7d 20 54 68 65 20 5b 73   {H16412} The [s
319c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
319d0 72 6f 72 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65  ror(C,V,N)] inte
319e0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
319f0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
31a00 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75       value of fu
31a10 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
31a20 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68  n exception with
31a30 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20   error code.**  
31a40 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
31a50 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46  ERROR] and a UTF
31a60 2d 38 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  -8 error message
31a70 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75   copied from V u
31a80 70 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  p to the.**     
31a90 20 20 20 20 20 66 69 72 73 74 20 7a 65 72 6f 20       first zero 
31aa0 62 79 74 65 20 6f 72 20 75 6e 74 69 6c 20 4e 20  byte or until N 
31ab0 62 79 74 65 73 20 61 72 65 20 72 65 61 64 20 69  bytes are read i
31ac0 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e  f N is positive.
31ad0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 35 7d 20  .**.** {H16415} 
31ae0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
31af0 75 6c 74 5f 65 72 72 6f 72 31 36 28 43 2c 56 2c  ult_error16(C,V,
31b00 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  N)] interface ch
31b10 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
31b20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
31b30 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
31b40 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74   to be an except
31b50 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63  ion with error c
31b60 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
31b70 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61  [SQLITE_ERROR] a
31b80 6e 64 20 61 20 55 54 46 2d 31 36 20 6e 61 74 69  nd a UTF-16 nati
31b90 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 65 72  ve byte order er
31ba0 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20  ror message.**  
31bb0 20 20 20 20 20 20 20 20 63 6f 70 69 65 64 20 66          copied f
31bc0 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65 20  rom V up to the 
31bd0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
31be0 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69 6c 20 4e  nator or until N
31bf0 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20   bytes.**       
31c00 20 20 20 61 72 65 20 72 65 61 64 20 69 66 20 4e     are read if N
31c10 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a   is positive..**
31c20 0a 2a 2a 20 7b 48 31 36 34 31 38 7d 20 54 68 65  .** {H16418} The
31c30 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
31c40 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 43 29  _error_toobig(C)
31c50 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
31c60 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
31c70 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
31c80 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
31c90 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
31ca0 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
31cb0 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
31cc0 20 20 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47    [SQLITE_TOOBIG
31cd0 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72  ] and an appropr
31ce0 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61  iate error messa
31cf0 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32  ge..**.** {H1642
31d00 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
31d10 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
31d20 65 6d 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  em(C)] interface
31d30 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
31d40 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
31d50 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e  value of the fun
31d60 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
31d70 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
31d80 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
31d90 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4e         [SQLITE_N
31da0 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70  OMEM] and an app
31db0 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d  ropriate error m
31dc0 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  essage..**.** {H
31dd0 31 36 34 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  16424} The [sqli
31de0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31df0 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69 6e 74 65  _code(C,E)] inte
31e00 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
31e10 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
31e20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
31e30 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  e function C to 
31e40 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
31e50 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 20  with error code 
31e60 45 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 54  E..**          T
31e70 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
31e80 20 74 65 78 74 20 69 73 20 75 6e 63 68 61 6e 67   text is unchang
31e90 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32  ed..**.** {H1642
31ea0 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
31eb0 72 65 73 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d  result_int(C,V)]
31ec0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
31ed0 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
31ee0 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
31ef0 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
31f00 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 69   be the 32-bit i
31f10 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a  nteger value V..
31f20 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 30 7d 20 54  **.** {H16430} T
31f30 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
31f40 6c 74 5f 69 6e 74 36 34 28 43 2c 56 29 5d 20 69  lt_int64(C,V)] i
31f50 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
31f60 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
31f70 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
31f80 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
31f90 65 20 74 68 65 20 36 34 2d 62 69 74 20 69 6e 74  e the 64-bit int
31fa0 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a  eger value V..**
31fb0 0a 2a 2a 20 7b 48 31 36 34 33 33 7d 20 54 68 65  .** {H16433} The
31fc0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
31fd0 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66  _null(C)] interf
31fe0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
31ff0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
32000 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
32010 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 4e 55 4c  tion C to be NUL
32020 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 36  L..**.** {H16436
32030 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
32040 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e  esult_text(C,V,N
32050 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
32060 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
32070 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
32080 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
32090 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d  C to be the UTF-
320a0 38 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20  8 string.**     
320b0 20 20 20 20 20 56 20 75 70 20 74 6f 20 74 68 65       V up to the
320c0 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
320d0 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20   is negative.** 
320e0 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
320f0 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66  first N bytes of
32100 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e   V if N is non-n
32110 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
32120 48 31 36 34 33 39 7d 20 54 68 65 20 5b 73 71 6c  H16439} The [sql
32130 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32140 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74  16(C,V,N,D)] int
32150 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
32160 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
32170 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
32180 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
32190 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76  the UTF-16 nativ
321a0 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
321b0 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
321c0 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
321d0 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e  t zero if N is n
321e0 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20  egative.**      
321f0 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74      or the first
32200 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66   N bytes of V if
32210 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
32220 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34  ve..**.** {H1644
32230 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
32240 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
32250 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
32260 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
32270 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
32280 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
32290 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
322a0 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69   UTF-16 big-endi
322b0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  an.**          s
322c0 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68  tring V up to th
322d0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20  e first zero if 
322e0 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  N is negative.**
322f0 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65            or the
32300 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f   first N bytes o
32310 72 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d  r V if N is non-
32320 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
32330 7b 48 31 36 34 34 35 7d 20 54 68 65 20 5b 73 71  {H16445} The [sq
32340 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32350 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16le(C,V,N,D)] 
32360 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
32370 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
32380 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
32390 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
323a0 62 65 20 74 68 65 20 55 54 46 2d 31 36 20 6c 69  be the UTF-16 li
323b0 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20  ttle-endian.**  
323c0 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56          string V
323d0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
323e0 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65   zero if N is ne
323f0 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  gative.**       
32400 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20     or the first 
32410 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20  N bytes of V if 
32420 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  N is non-negativ
32430 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 38  e..**.** {H16448
32440 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
32450 65 73 75 6c 74 5f 76 61 6c 75 65 28 43 2c 56 29  esult_value(C,V)
32460 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
32470 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
32480 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
32490 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
324a0 6f 20 62 65 20 74 68 65 20 5b 75 6e 70 72 6f 74  o be the [unprot
324b0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
324c0 6c 75 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  lue].**         
324d0 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a   object V..**.**
324e0 20 7b 48 31 36 34 35 31 7d 20 54 68 65 20 5b 73   {H16451} The [s
324f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
32500 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74  roblob(C,N)] int
32510 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
32520 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
32530 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
32540 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
32550 61 6e 20 4e 2d 62 79 74 65 20 42 4c 4f 42 20 6f  an N-byte BLOB o
32560 66 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a  f all zeros..**.
32570 2a 2a 20 7b 48 31 36 34 35 34 7d 20 54 68 65 20  ** {H16454} The 
32580 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32590 65 72 72 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71  error()] and [sq
325a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
325b0 6f 72 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20  or16()].**      
325c0 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 6d      interfaces m
325d0 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ake a copy of th
325e0 65 69 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67  eir error messag
325f0 65 20 73 74 72 69 6e 67 73 20 62 65 66 6f 72 65  e strings before
32600 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
32610 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  urning..**.** {H
32620 31 36 34 35 37 7d 20 49 66 20 74 68 65 20 44 20  16457} If the D 
32630 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d  destructor param
32640 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
32650 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56  _result_blob(C,V
32660 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
32670 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
32680 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44  ult_text(C,V,N,D
32690 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  )], [sqlite3_res
326a0 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e  ult_text16(C,V,N
326b0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
326c0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
326d0 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e  t_text16be(C,V,N
326e0 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
326f0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
32700 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c  sult_text16le(C,
32710 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63  V,N,D)] is the c
32720 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f  onstant [SQLITE_
32730 53 54 41 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20  STATIC].**      
32740 20 20 20 20 74 68 65 6e 20 6e 6f 20 64 65 73 74      then no dest
32750 72 75 63 74 6f 72 20 69 73 20 65 76 65 72 20 63  ructor is ever c
32760 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 70 6f 69  alled on the poi
32770 6e 74 65 72 20 56 20 61 6e 64 20 53 51 4c 69 74  nter V and SQLit
32780 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  e.**          as
32790 73 75 6d 65 73 20 74 68 61 74 20 56 20 69 73 20  sumes that V is 
327a0 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  immutable..**.**
327b0 20 7b 48 31 36 34 36 30 7d 20 49 66 20 74 68 65   {H16460} If the
327c0 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61   D destructor pa
327d0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
327e0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
327f0 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
32800 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
32810 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c  result_text(C,V,
32820 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  N,D)], [sqlite3_
32830 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c  result_text16(C,
32840 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
32850 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
32860 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c  sult_text16be(C,
32870 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,N,D)], or.**  
32880 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
32890 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
328a0 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68  (C,V,N,D)] is th
328b0 65 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20  e constant.**   
328c0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54         [SQLITE_T
328d0 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 74  RANSIENT] then t
328e0 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  he interfaces ma
328f0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
32900 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
32910 6e 74 65 6e 74 20 6f 66 20 56 20 61 6e 64 20 72  ntent of V and r
32920 65 74 61 69 6e 73 20 74 68 65 20 63 6f 70 79 2e  etains the copy.
32930 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 33 7d 20  .**.** {H16463} 
32940 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63  If the D destruc
32950 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f  tor parameter to
32960 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
32970 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _blob(C,V,N,D)],
32980 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
32990 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
329a0 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71  t(C,V,N,D)], [sq
329b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
329c0 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  t16(C,V,N,D)],.*
329d0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
329e0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
329f0 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f  6be(C,V,N,D)], o
32a00 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
32a10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32a20 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d  xt16le(C,V,N,D)]
32a30 20 69 73 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f   is some value o
32a40 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20  ther than.**    
32a50 20 20 20 20 20 20 74 68 65 20 63 6f 6e 73 74 61        the consta
32a60 6e 74 73 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  nts [SQLITE_STAT
32a70 49 43 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  IC] and [SQLITE_
32a80 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 0a  TRANSIENT] then.
32a90 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69  **          SQLi
32aa0 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
32ab0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20  he destructor D 
32ac0 77 69 74 68 20 56 20 61 73 20 69 74 73 20 6f 6e  with V as its on
32ad0 6c 79 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20  ly argument.**  
32ae0 20 20 20 20 20 20 20 20 77 68 65 6e 20 69 74 20          when it 
32af0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
32b00 68 20 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a  h the V value..*
32b10 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
32b20 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
32b30 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
32b40 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
32b50 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
32b60 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32b70 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
32b80 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
32b90 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
32ba0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
32bb0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32bc0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
32bd0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
32be0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
32bf0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32c00 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
32c10 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
32c20 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
32c30 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
32c40 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
32c50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32c60 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
32c70 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
32c80 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
32c90 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
32ca0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
32cb0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
32cc0 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
32cd0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
32ce0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
32cf0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
32d00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32d10 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
32d20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32d30 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
32d40 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
32d50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32d60 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
32d70 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
32d80 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
32d90 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
32da0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32db0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
32dc0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
32dd0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
32de0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
32df0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32e00 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
32e10 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
32e20 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
32e30 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
32e40 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
32e50 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
32e60 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
32e70 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
32e80 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
32e90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32ea0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
32eb0 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
32ec0 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
32ed0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
32ee0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
32ef0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
32f00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32f10 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
32f20 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20  ating Sequences 
32f30 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 33 30 30  {H16600} <S20300
32f40 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  >.**.** These fu
32f50 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64  nctions are used
32f60 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c   to add new coll
32f70 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
32f80 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  to the.** [datab
32f90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
32fa0 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
32fb0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
32fc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  .**.** The name 
32fd0 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61  of the new colla
32fe0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
32ff0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20   specified as a 
33000 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
33010 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
33020 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
33030 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
33040 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
33050 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
33060 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69   string for sqli
33070 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33080 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c  tion16(). In all
33090 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61   cases.** the na
330a0 6d 65 20 69 73 20 70 61 73 73 65 64 20 61 73 20  me is passed as 
330b0 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
330c0 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
330d0 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72  .** The third ar
330e0 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e  gument may be on
330f0 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e  e of the constan
33100 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ts [SQLITE_UTF8]
33110 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  ,.** [SQLITE_UTF
33120 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45  16LE] or [SQLITE
33130 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63  _UTF16BE], indic
33140 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 75  ating that the u
33150 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ser-supplied.** 
33160 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20  routine expects 
33170 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69  to be passed poi
33180 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
33190 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
331a0 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  TF-8,.** UTF-16 
331b0 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f  little-endian, o
331c0 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64  r UTF-16 big-end
331d0 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
331e0 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  y. The.** third 
331f0 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61  argument might a
33200 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55  lso be [SQLITE_U
33210 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f  TF16_ALIGNED] to
33220 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 0a 2a   indicate that.*
33230 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78  * the routine ex
33240 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74  pects pointers t
33250 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c  o 16-bit word al
33260 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  igned strings.**
33270 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68   of UTF-16 in th
33280 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
33290 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
332a0 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  computer..**.** 
332b0 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
332c0 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72   user supplied r
332d0 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70  outine must be p
332e0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66  assed as the fif
332f0 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  th.** argument. 
33300 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20   If it is NULL, 
33310 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65  this is the same
33320 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65   as deleting the
33330 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
33340 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20  quence (so that 
33350 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61  SQLite cannot ca
33360 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a  ll it anymore)..
33370 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68 65  ** Each time the
33380 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70   application sup
33390 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  plied function i
333a0 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73  s invoked, it is
333b0 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74   passed.** as it
333c0 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
333d0 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  r a copy of the 
333e0 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 20  void* passed as 
333f0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
33400 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
33410 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33420 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  on() or sqlite3_
33430 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33440 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  16()..**.** The 
33450 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65  remaining argume
33460 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69  nts to the appli
33470 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20  cation-supplied 
33480 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20  routine are two 
33490 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68  strings,.** each
334a0 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
334b0 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29  a (length, data)
334c0 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65   pair and encode
334d0 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e  d in the encodin
334e0 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61  g.** that was pa
334f0 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
33500 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20  d argument when 
33510 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  the collation se
33520 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65  quence was.** re
33530 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20  gistered. {END} 
33540 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
33550 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69   defined collati
33560 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  on routine shoul
33570 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61  d.** return nega
33580 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f  tive, zero or po
33590 73 69 74 69 76 65 20 69 66 20 74 68 65 20 66 69  sitive if the fi
335a0 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65  rst string is le
335b0 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61  ss than,.** equa
335c0 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
335d0 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
335e0 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53   string. i.e. (S
335f0 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32  TRING1 - STRING2
33600 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
33610 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33620 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73  ation_v2() works
33630 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72   like sqlite3_cr
33640 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
33650 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
33660 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72  it takes an extr
33670 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  a argument which
33680 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
33690 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c   for.** the coll
336a0 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74  ation.  The dest
336b0 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
336c0 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   when the collat
336d0 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f  ion is.** destro
336e0 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65  yed and is passe
336f0 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  d a copy of the 
33700 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
33710 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a   void* pointer.*
33720 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
33730 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
33740 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61  n_v2()..** Colla
33750 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f  tions are destro
33760 79 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72  yed when they ar
33770 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
33780 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74  later calls to t
33790 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20  he.** collation 
337a0 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  creation functio
337b0 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b  ns or when the [
337c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
337d0 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a  ion] is closed.*
337e0 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
337f0 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
33800 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
33810 2a 2a 20 7b 48 31 36 36 30 33 7d 20 41 20 73 75  ** {H16603} A su
33820 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
33830 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
33840 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33850 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
33860 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e 74 65  X,E,P,F,D)] inte
33870 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20  rface.**        
33880 20 20 72 65 67 69 73 74 65 72 73 20 66 75 6e 63    registers func
33890 74 69 6f 6e 20 46 20 61 73 20 74 68 65 20 63 6f  tion F as the co
338a0 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f  mparison functio
338b0 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20  n used to.**    
338c0 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74 20        implement 
338d0 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 74  collation X on t
338e0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
338f0 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a  nection] B for.*
33900 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
33910 61 73 65 73 20 68 61 76 69 6e 67 20 65 6e 63 6f  ases having enco
33920 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ding E..**.** {H
33930 31 36 36 30 34 7d 20 53 51 4c 69 74 65 20 75 6e  16604} SQLite un
33940 64 65 72 73 74 61 6e 64 73 20 74 68 65 20 58 20  derstands the X 
33950 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
33960 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
33970 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33980 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
33990 44 29 5d 20 61 73 20 61 20 7a 65 72 6f 2d 74 65  D)] as a zero-te
339a0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20  rminated.**     
339b0 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e       UTF-8 strin
339c0 67 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  g in which case 
339d0 69 73 20 69 67 6e 6f 72 65 64 20 66 6f 72 20 41  is ignored for A
339e0 53 43 49 49 20 63 68 61 72 61 63 74 65 72 73 20  SCII characters 
339f0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
33a00 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74 20 66  is significant f
33a10 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61  or non-ASCII cha
33a20 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b  racters..**.** {
33a30 48 31 36 36 30 36 7d 20 53 75 63 63 65 73 73 69  H16606} Successi
33a40 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ve calls to [sql
33a50 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33a60 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
33a70 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,F,D)].**       
33a80 20 20 20 77 69 74 68 20 74 68 65 20 73 61 6d 65     with the same
33a90 20 76 61 6c 75 65 73 20 66 6f 72 20 42 2c 20 58   values for B, X
33aa0 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72 72 69 64  , and E, overrid
33ab0 65 20 70 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a  e prior values.*
33ac0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 50 2c  *          of P,
33ad0 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a   F, and D..**.**
33ae0 20 7b 48 31 36 36 30 39 7d 20 49 66 20 74 68 65   {H16609} If the
33af0 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 69 6e   destructor D in
33b00 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33b10 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
33b20 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20  X,E,P,F,D)].**  
33b30 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74 20 4e          is not N
33b40 55 4c 4c 20 74 68 65 6e 20 69 74 20 69 73 20 63  ULL then it is c
33b50 61 6c 6c 65 64 20 77 69 74 68 20 61 72 67 75 6d  alled with argum
33b60 65 6e 74 20 50 20 77 68 65 6e 20 74 68 65 0a 2a  ent P when the.*
33b70 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
33b80 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
33b90 20 64 72 6f 70 70 65 64 20 62 79 20 53 51 4c 69   dropped by SQLi
33ba0 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31  te..**.** {H1661
33bb0 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66  2} A collating f
33bc0 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70  unction is dropp
33bd0 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 6f 76  ed when it is ov
33be0 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  erloaded..**.** 
33bf0 7b 48 31 36 36 31 35 7d 20 41 20 63 6f 6c 6c 61  {H16615} A colla
33c00 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
33c10 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20 74 68   dropped when th
33c20 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
33c30 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
33c40 20 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e    is closed usin
33c50 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  g [sqlite3_close
33c60 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  ()]..**.** {H166
33c70 31 38 7d 20 54 68 65 20 70 6f 69 6e 74 65 72 20  18} The pointer 
33c80 50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72  P in [sqlite3_cr
33c90 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
33ca0 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a  2(B,X,E,P,F,D)].
33cb0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 70  **          is p
33cc0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
33cd0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
33ce0 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6d 70  eter to the comp
33cf0 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  arison.**       
33d00 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f     function F fo
33d10 72 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  r all subsequent
33d20 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
33d30 46 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 31  F..**.** {H16621
33d40 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  } A call to [sql
33d50 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33d60 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29  ation(B,X,E,P,F)
33d70 5d 20 69 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20  ] is exactly.** 
33d80 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d           the sam
33d90 65 20 61 73 20 61 20 63 61 6c 6c 20 74 6f 20 5b  e as a call to [
33da0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
33db0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 20 77  ollation_v2()] w
33dc0 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
33dd0 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74  the same paramet
33de0 65 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64  ers and a NULL d
33df0 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a  estructor..**.**
33e00 20 7b 48 31 36 36 32 34 7d 20 46 6f 6c 6c 6f 77   {H16624} Follow
33e10 69 6e 67 20 61 20 5b 73 71 6c 69 74 65 33 5f 63  ing a [sqlite3_c
33e20 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
33e30 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
33e40 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  ,.**          SQ
33e50 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 63 6f  Lite uses the co
33e60 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f  mparison functio
33e70 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74 65 78 74  n F for all text
33e80 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20   comparison.**  
33e90 20 20 20 20 20 20 20 20 6f 70 65 72 61 74 69 6f          operatio
33ea0 6e 73 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ns on the [datab
33eb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
33ec0 42 20 6f 6e 20 74 65 78 74 20 76 61 6c 75 65 73  B on text values
33ed0 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
33ee0 20 20 75 73 65 20 74 68 65 20 63 6f 6c 6c 61 74    use the collat
33ef0 69 6e 67 20 73 65 71 75 65 6e 63 65 20 6e 61 6d  ing sequence nam
33f00 65 64 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ed X..**.** {H16
33f10 36 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  627} The [sqlite
33f20 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33f30 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d  on16(B,X,E,P,F)]
33f40 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 0a   works the same.
33f50 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 5b  **          as [
33f60 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
33f70 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50  ollation(B,X,E,P
33f80 2c 46 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  ,F)] except that
33f90 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
33fa0 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20   collation name 
33fb0 58 20 69 73 20 75 6e 64 65 72 73 74 6f 6f 64 20  X is understood 
33fc0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
33fd0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a  ive byte order.*
33fe0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 74 65  *          inste
33ff0 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a  ad of UTF-8..**.
34000 2a 2a 20 7b 48 31 36 36 33 30 7d 20 57 68 65 6e  ** {H16630} When
34010 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72   multiple compar
34020 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61  ison functions a
34030 72 65 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72  re available for
34040 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20   the same.**    
34050 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20        collating 
34060 73 65 71 75 65 6e 63 65 2c 20 53 51 4c 69 74 65  sequence, SQLite
34070 20 63 68 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65   chooses the one
34080 20 77 68 6f 73 65 20 74 65 78 74 20 65 6e 63 6f   whose text enco
34090 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ding.**         
340a0 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65   requires the le
340b0 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f  ast amount of co
340c0 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68  nversion from th
340d0 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20  e default.**    
340e0 20 20 20 20 20 20 74 65 78 74 20 65 6e 63 6f 64        text encod
340f0 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62  ing of the datab
34100 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ase..*/.int sqli
34110 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
34120 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  tion(.  sqlite3*
34130 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
34140 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
34150 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
34160 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
34170 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
34180 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
34190 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
341a0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
341b0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
341c0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
341d0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
341e0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
341f0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
34200 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
34210 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
34220 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
34230 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
34240 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
34250 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
34260 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
34270 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
34280 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d  const void *zNam
34290 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  e,.  int eTextRe
342a0 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
342b0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
342c0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
342d0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
342e0 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
342f0 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69  API3REF: Collati
34300 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61  on Needed Callba
34310 63 6b 73 20 7b 48 31 36 37 30 30 7d 20 3c 53 32  cks {H16700} <S2
34320 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61  0300>.**.** To a
34330 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
34340 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
34350 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
34360 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
34370 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
34380 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
34390 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
343a0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
343b0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
343c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
343d0 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68   to be called wh
343e0 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
343f0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  ned collation.**
34400 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71   sequence is req
34410 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  uired..**.** If 
34420 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
34430 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
34440 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
34450 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
34460 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  API,.** then it 
34470 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61  is passed the na
34480 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64  mes of undefined
34490 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
344a0 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a  nces as strings.
344b0 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  ** encoded in UT
344c0 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d 20 49 66  F-8. {H16703} If
344d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
344e0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
344f0 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61   used,.** the na
34500 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61  mes are passed a
34510 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
34520 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
34530 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c  order..** A call
34540 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74   to either funct
34550 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79  ion replaces any
34560 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61   existing callba
34570 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ck..**.** When t
34580 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
34590 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
345a0 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
345b0 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
345c0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
345d0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
345e0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
345f0 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
34600 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
34610 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
34620 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
34630 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
34640 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
34650 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
34660 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
34670 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
34680 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
34690 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
346a0 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
346b0 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
346c0 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
346d0 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
346e0 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
346f0 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
34700 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
34710 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
34720 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
34730 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a  tion sequence..*
34740 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
34750 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
34760 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
34770 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
34780 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
34790 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
347a0 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
347b0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
347c0 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
347d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
347e0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
347f0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
34800 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 32 7d 20  .**.** {H16702} 
34810 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
34820 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
34830 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44  llation_needed(D
34840 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,P,F)].**       
34850 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63     or [sqlite3_c
34860 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
34870 36 28 44 2c 50 2c 46 29 5d 20 63 61 75 73 65 73  6(D,P,F)] causes
34880 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
34890 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
348a0 63 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f  ction] D to invo
348b0 6b 65 20 63 61 6c 6c 62 61 63 6b 20 46 20 77 69  ke callback F wi
348c0 74 68 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20  th first.**     
348d0 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 50       parameter P
348e0 20 77 68 65 6e 65 76 65 72 20 69 74 20 6e 65 65   whenever it nee
348f0 64 73 20 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20  ds a comparison 
34900 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a  function for a.*
34910 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
34920 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 74 68  ting sequence th
34930 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b  at it does not k
34940 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a  now about..**.**
34950 20 7b 48 31 36 37 30 34 7d 20 45 61 63 68 20 73   {H16704} Each s
34960 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
34970 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  o [sqlite3_colla
34980 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f  tion_needed()] o
34990 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
349a0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
349b0 5f 6e 65 65 64 65 64 31 36 28 29 5d 20 6f 76 65  _needed16()] ove
349c0 72 72 69 64 65 73 20 74 68 65 20 63 61 6c 6c 62  rrides the callb
349d0 61 63 6b 20 72 65 67 69 73 74 65 72 65 64 0a 2a  ack registered.*
349e0 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68  *          on th
349f0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
34a00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20   connection] by 
34a10 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65  prior calls to e
34a20 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
34a30 20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a    interface..**.
34a40 2a 2a 20 7b 48 31 36 37 30 36 7d 20 54 68 65 20  ** {H16706} The 
34a50 6e 61 6d 65 20 6f 66 20 74 68 65 20 72 65 71 75  name of the requ
34a60 65 73 74 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20  ested collating 
34a70 66 75 6e 63 74 69 6f 6e 20 70 61 73 73 65 64 20  function passed 
34a80 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
34a90 20 20 20 34 74 68 20 70 61 72 61 6d 65 74 65 72     4th parameter
34aa0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
34ab0 20 69 73 20 69 6e 20 55 54 46 2d 38 20 69 66 20   is in UTF-8 if 
34ac0 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
34ad0 20 20 20 20 20 20 20 20 20 77 61 73 20 72 65 67           was reg
34ae0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73  istered using [s
34af0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
34b00 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a  _needed()] and.*
34b10 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e  *          is in
34b20 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
34b30 79 74 65 20 6f 72 64 65 72 20 69 66 20 74 68 65  yte order if the
34b40 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a   callback was.**
34b50 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
34b60 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ered using [sqli
34b70 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
34b80 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e  eded16()]..*/.in
34b90 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
34ba0 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71  ion_needed(.  sq
34bb0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
34bc0 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
34bd0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
34be0 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63  eTextRep,const c
34bf0 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  har*).);.int sql
34c00 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
34c10 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74  eeded16(.  sqlit
34c20 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  e3*, .  void*,. 
34c30 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
34c40 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
34c50 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  tRep,const void*
34c60 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63  ).);../*.** Spec
34c70 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20  ify the key for 
34c80 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74  an encrypted dat
34c90 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75  abase.  This rou
34ca0 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  tine should be.*
34cb0 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61  * called right a
34cc0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  fter sqlite3_ope
34cd0 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n()..**.** The c
34ce0 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
34cf0 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
34d00 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
34d10 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
34d20 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
34d30 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  /.int sqlite3_ke
34d40 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
34d50 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
34d60 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
34d70 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
34d80 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
34d90 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
34da0 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a    /* The key */.
34db0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65  );../*.** Change
34dc0 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f   the key on an o
34dd0 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49  pen database.  I
34de0 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  f the current da
34df0 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a  tabase is not.**
34e00 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73   encrypted, this
34e10 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e   routine will en
34e20 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e  crypt it.  If pN
34e30 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30  ew==0 or nNew==0
34e40 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  , the.** databas
34e50 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a  e is decrypted..
34e60 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
34e70 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
34e80 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
34e90 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
34ea0 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
34eb0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
34ec0 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a   sqlite3_rekey(.
34ed0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
34ee0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34ef0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
34f00 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
34f10 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
34f20 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
34f30 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f  * The new key */
34f40 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
34f50 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65  REF: Suspend Exe
34f60 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f  cution For A Sho
34f70 72 74 20 54 69 6d 65 20 7b 48 31 30 35 33 30 7d  rt Time {H10530}
34f80 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S40410>.**.** 
34f90 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
34fa0 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  p() function cau
34fb0 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
34fc0 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
34fd0 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
34fe0 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
34ff0 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
35000 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
35010 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
35020 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  .**.** If the op
35030 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64  erating system d
35040 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20  oes not support 
35050 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77  sleep requests w
35060 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f  ith.** milliseco
35070 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69  nd time resoluti
35080 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d  on, then the tim
35090 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65  e will be rounde
350a0 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e  d up to.** the n
350b0 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54  earest second. T
350c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
350d0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
350e0 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72  ep actually.** r
350f0 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
35100 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
35110 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
35120 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
35130 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
35140 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
35150 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
35160 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
35170 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
35180 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
35190 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
351a0 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 33 7d 20 54  **.** {H10533} T
351b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65  he [sqlite3_slee
351c0 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20  p(M)] interface 
351d0 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 6c 65  invokes the xSle
351e0 65 70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  ep.**          m
351f0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
35200 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
35210 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20  s|VFS] in order 
35220 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  to.**          s
35230 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
35240 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   of the current 
35250 74 68 72 65 61 64 20 66 6f 72 20 61 74 20 6c 65  thread for at le
35260 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ast.**          
35270 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a  M milliseconds..
35280 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 36 7d 20 54  **.** {H10536} T
35290 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65  he [sqlite3_slee
352a0 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20  p(M)] interface 
352b0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
352c0 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  er of.**        
352d0 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f    milliseconds o
352e0 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
352f0 20 72 65 71 75 65 73 74 65 64 20 6f 66 20 74 68   requested of th
35300 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20  e operating.**  
35310 20 20 20 20 20 20 20 20 73 79 73 74 65 6d 2c 20          system, 
35320 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6c  which might be l
35330 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 70  arger than the p
35340 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69  arameter M..*/.i
35350 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  nt sqlite3_sleep
35360 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
35370 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
35380 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69  The Folder Holdi
35390 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c  ng Temporary Fil
353a0 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53 32 30  es {H10310} <S20
353b0 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  000>.**.** If th
353c0 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  is global variab
353d0 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  le is made to po
353e0 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
353f0 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20  which is.** the 
35400 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72  name of a folder
35410 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f   (a.k.a. directo
35420 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65  ry), then all te
35430 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a  mporary files.**
35440 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69   created by SQLi
35450 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65  te will be place
35460 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74  d in that direct
35470 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61  ory.  If this va
35480 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e  riable.** is a N
35490 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
354a0 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d  n SQLite perform
354b0 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61  s a search for a
354c0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a  n appropriate.**
354d0 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20   temporary file 
354e0 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
354f0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
35500 74 6f 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  to modify this v
35510 61 72 69 61 62 6c 65 20 6f 6e 63 65 20 61 20 5b  ariable once a [
35520 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35530 69 6f 6e 5d 0a 2a 2a 20 68 61 73 20 62 65 65 6e  ion].** has been
35540 20 6f 70 65 6e 65 64 2e 20 20 49 74 20 69 73 20   opened.  It is 
35550 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68  intended that th
35560 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73  is variable be s
35570 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61  et once.** as pa
35580 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e  rt of process in
35590 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
355a0 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69   before any SQLi
355b0 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  te interface.** 
355c0 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65  routines have be
355d0 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65 6d 61  en call and rema
355e0 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 74 68 65  in unchanged the
355f0 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49  reafter..*/.SQLI
35600 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a  TE_EXTERN char *
35610 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
35620 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ectory;../*.** C
35630 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f  API3REF: Test Fo
35640 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f  r Auto-Commit Mo
35650 64 65 20 7b 48 31 32 39 33 30 7d 20 3c 53 36 30  de {H12930} <S60
35660 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  200>.** KEYWORDS
35670 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  : {autocommit mo
35680 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  de}.**.** The sq
35690 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
356a0 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  mmit() interface
356b0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
356c0 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  o or.** zero if 
356d0 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61  the given databa
356e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
356f0 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75   or is not in au
35700 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a  tocommit mode,.*
35710 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
35720 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
35730 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c   is on by defaul
35740 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74  t..** Autocommit
35750 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65   mode is disable
35760 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73  d by a [BEGIN] s
35770 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74  tatement..** Aut
35780 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
35790 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20  re-enabled by a 
357a0 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c  [COMMIT] or [ROL
357b0 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  LBACK]..**.** If
357c0 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f   certain kinds o
357d0 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f  f errors occur o
357e0 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69  n a statement wi
357f0 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61  thin a multi-sta
35800 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61  tement.** transa
35810 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e  ction (errors in
35820 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f  cluding [SQLITE_
35830 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  FULL], [SQLITE_I
35840 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  OERR],.** [SQLIT
35850 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54  E_NOMEM], [SQLIT
35860 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51  E_BUSY], and [SQ
35870 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29  LITE_INTERRUPT])
35880 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61   then the.** tra
35890 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62  nsaction might b
358a0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
358b0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
358c0 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a  e only way to.**
358d0 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65   find out whethe
358e0 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  r SQLite automat
358f0 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
35900 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
35910 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65  on after.** an e
35920 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74  rror is to use t
35930 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
35940 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
35950 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 31 7d 20 54  **.** {H12931} T
35960 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  he [sqlite3_get_
35970 61 75 74 6f 63 6f 6d 6d 69 74 28 44 29 5d 20 69  autocommit(D)] i
35980 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
35990 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20   non-zero or.** 
359a0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 69 66           zero if
359b0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
359c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69 73 20  onnection] D is 
359d0 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
359e0 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20 20 20 20 20  ocommit.**      
359f0 20 20 20 20 6d 6f 64 65 2c 20 72 65 73 70 65 63      mode, respec
35a00 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tively..**.** {H
35a10 31 32 39 33 32 7d 20 41 75 74 6f 63 6f 6d 6d 69  12932} Autocommi
35a20 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20  t mode is on by 
35a30 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b  default..**.** {
35a40 48 31 32 39 33 33 7d 20 41 75 74 6f 63 6f 6d 6d  H12933} Autocomm
35a50 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62  it mode is disab
35a60 6c 65 64 20 62 79 20 61 20 73 75 63 63 65 73 73  led by a success
35a70 66 75 6c 20 5b 42 45 47 49 4e 5d 20 73 74 61 74  ful [BEGIN] stat
35a80 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ement..**.** {H1
35a90 32 39 33 34 7d 20 41 75 74 6f 63 6f 6d 6d 69 74  2934} Autocommit
35aa0 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
35ab0 20 62 79 20 61 20 73 75 63 63 65 73 73 66 75 6c   by a successful
35ac0 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
35ad0 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20 20 20 20 20  LLBACK].**      
35ae0 20 20 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a      statement..*
35af0 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
35b00 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 39 33 36 7d  :.**.** {A12936}
35b10 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
35b20 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61  ad changes the a
35b30 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73  utocommit status
35b40 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
35b50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
35b60 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
35b70 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75  is routine is ru
35b80 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nning, then the 
35b90 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
35ba0 20 20 20 20 20 20 20 20 20 69 73 20 75 6e 64 65           is unde
35bb0 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
35bc0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
35bd0 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  mmit(sqlite3*);.
35be0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35bf0 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61   Find The Databa
35c00 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50  se Handle Of A P
35c10 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
35c20 74 20 7b 48 31 33 31 32 30 7d 20 3c 53 36 30 36  t {H13120} <S606
35c30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
35c40 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
35c50 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
35c60 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
35c70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
35c80 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61  le.** to which a
35c90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
35ca0 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20  ment] belongs.  
35cb0 54 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  The database han
35cc0 64 6c 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a  dle returned by.
35cd0 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  ** sqlite3_db_ha
35ce0 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65  ndle is the same
35cf0 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
35d00 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69   that was the fi
35d10 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
35d20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
35d30 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61  prepare_v2()] ca
35d40 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61  ll (or its varia
35d50 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73  nts) that was us
35d60 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20  ed to.** create 
35d70 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  the statement in
35d80 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65   the first place
35d90 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
35da0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 32  TS:.**.** {H1312
35db0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
35dc0 64 62 5f 68 61 6e 64 6c 65 28 53 29 5d 20 69 6e  db_handle(S)] in
35dd0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
35de0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20  a pointer.**    
35df0 20 20 20 20 20 20 74 6f 20 74 68 65 20 5b 64 61        to the [da
35e00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35e10 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  n] associated wi
35e20 74 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  th the.**       
35e30 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
35e40 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71  tement] S..*/.sq
35e50 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
35e60 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
35e70 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
35e80 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74  CAPI3REF: Find t
35e90 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64  he next prepared
35ea0 20 73 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31   statement {H131
35eb0 34 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a  40} <S60600>.**.
35ec0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
35ed0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
35ee0 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ter to the next 
35ef0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
35f00 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53  ent] after.** pS
35f10 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  tmt associated w
35f20 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
35f30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44  e connection] pD
35f40 62 2e 20 20 49 66 20 70 53 74 6d 74 20 69 73 20  b.  If pStmt is 
35f50 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69  NULL.** then thi
35f60 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
35f70 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
35f80 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61   the first prepa
35f90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
35fa0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
35fb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
35fc0 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 49  nnection pDb.  I
35fd0 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74  f no prepared st
35fe0 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73  atement.** satis
35ff0 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69  fies the conditi
36000 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ons of this rout
36010 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ine, it returns 
36020 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  NULL..**.** INVA
36030 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
36040 31 33 31 34 33 7d 20 49 66 20 44 20 69 73 20 61  13143} If D is a
36050 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36060 63 74 69 6f 6e 5d 20 74 68 61 74 20 68 6f 6c 64  ction] that hold
36070 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
36080 20 20 20 20 20 20 20 20 20 20 75 6e 66 69 6e 61            unfina
36090 6c 69 7a 65 64 20 5b 70 72 65 70 61 72 65 64 20  lized [prepared 
360a0 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20  statements] and 
360b0 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  S is a NULL poin
360c0 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ter,.**         
360d0 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6e   then [sqlite3_n
360e0 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20  ext_stmt(D, S)] 
360f0 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65  routine shall re
36100 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  turn a pointer.*
36110 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 6f 6e  *          to on
36120 65 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65  e of the prepare
36130 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73  d statements ass
36140 6f 63 69 61 74 65 64 20 77 69 74 68 20 44 2e 0a  ociated with D..
36150 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 36 7d 20 49  **.** {H13146} I
36160 66 20 44 20 69 73 20 61 20 5b 64 61 74 61 62 61  f D is a [databa
36170 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
36180 68 61 74 20 68 6f 6c 64 73 20 6e 6f 20 75 6e 66  hat holds no unf
36190 69 6e 61 6c 69 7a 65 64 0a 2a 2a 20 20 20 20 20  inalized.**     
361a0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
361b0 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53  tatements] and S
361c0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
361d0 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  er, then.**     
361e0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65       [sqlite3_ne
361f0 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72  xt_stmt(D, S)] r
36200 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74  outine shall ret
36210 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  urn a NULL point
36220 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34  er..**.** {H1314
36230 39 7d 20 49 66 20 53 20 69 73 20 61 20 5b 70 72  9} If S is a [pr
36240 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
36250 5d 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61  ] in the [databa
36260 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
36270 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
36280 20 53 20 69 73 20 6e 6f 74 20 74 68 65 20 6c 61   S is not the la
36290 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
362a0 65 6d 65 6e 74 20 69 6e 20 44 2c 20 74 68 65 6e  ement in D, then
362b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
362c0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
362d0 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73  D, S)] routine s
362e0 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 70 6f  hall return a po
362f0 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  inter.**        
36300 20 20 74 6f 20 74 68 65 20 6e 65 78 74 20 70 72    to the next pr
36310 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
36320 20 69 6e 20 44 20 61 66 74 65 72 20 53 2e 0a 2a   in D after S..*
36330 2a 0a 2a 2a 20 7b 48 31 33 31 35 32 7d 20 49 66  *.** {H13152} If
36340 20 53 20 69 73 20 74 68 65 20 6c 61 73 74 20 5b   S is the last [
36350 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
36360 6e 74 5d 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  nt] in the.**   
36370 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
36380 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74   connection] D t
36390 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
363a0 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29  _next_stmt(D, S)
363b0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f  ].**          ro
363c0 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75  utine shall retu
363d0 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  rn a NULL pointe
363e0 72 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54  r..**.** ASSUMPT
363f0 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 33  IONS:.**.** {A13
36400 31 35 34 7d 20 54 68 65 20 5b 64 61 74 61 62 61  154} The [databa
36410 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
36420 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61  ointer D in a ca
36430 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ll to.**        
36440 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f    [sqlite3_next_
36450 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20  stmt(D,S)] must 
36460 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e  refer to an open
36470 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20   database.**    
36480 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e        connection
36490 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c   and in particul
364a0 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61  ar must not be a
364b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
364c0 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  /.sqlite3_stmt *
364d0 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
364e0 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20  t(sqlite3 *pDb, 
364f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
36500 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
36510 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e  I3REF: Commit An
36520 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66  d Rollback Notif
36530 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
36540 73 20 7b 48 31 32 39 35 30 7d 20 3c 53 36 30 34  s {H12950} <S604
36550 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
36560 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
36570 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
36580 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
36590 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
365a0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
365b0 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
365c0 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64  ion is committed
365d0 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63  ..** Any callbac
365e0 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
365f0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ous call to sqli
36600 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
36610 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
36620 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
36630 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
36640 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  den..** The sqli
36650 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
36660 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
36670 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
36680 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
36690 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
366a0 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
366b0 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64  ion is committed
366c0 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63  ..** Any callbac
366d0 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
366e0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ous call to sqli
366f0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
36700 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
36710 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
36720 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
36730 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67  den..** The pArg
36740 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73   argument is pas
36750 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74  sed through to t
36760 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  he callback..** 
36770 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
36780 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b  on a commit hook
36790 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
367a0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74  s non-zero,.** t
367b0 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69  hen the commit i
367c0 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
367d0 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a   a rollback..**.
367e0 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75  ** If another fu
367f0 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69  nction was previ
36800 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64  ously registered
36810 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67 20 76 61  , its.** pArg va
36820 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
36830 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c    Otherwise NULL
36840 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
36850 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 6e 67 20  .** Registering 
36860 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20  a NULL function 
36870 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c  disables the cal
36880 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  lback..**.** For
36890 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
368a0 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61   this API, a tra
368b0 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64  nsaction is said
368c0 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a   to have been.**
368d0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20   rolled back if 
368e0 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c  an explicit "ROL
368f0 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74  LBACK" statement
36900 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72   is executed, or
36910 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  .** an error or 
36920 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65  constraint cause
36930 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f  s an implicit ro
36940 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e  llback to occur.
36950 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b  .** The rollback
36960 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74   callback is not
36970 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72   invoked if a tr
36980 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20  ansaction is.** 
36990 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
369a0 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73  lled back becaus
369b0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
369c0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
369d0 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c  sed..** The roll
369e0 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  back callback is
369f0 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20   not invoked if 
36a00 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
36a10 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
36a20 62 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74  because a commit
36a30 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
36a40 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20  ed non-zero..** 
36a50 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20  <todo> Check on 
36a60 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  this </todo>.**.
36a70 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
36a80 2a 0a 2a 2a 20 7b 48 31 32 39 35 31 7d 20 54 68  *.** {H12951} Th
36a90 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  e [sqlite3_commi
36aa0 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  t_hook(D,F,P)] i
36ab0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
36ac0 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  rs the.**       
36ad0 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63     callback func
36ae0 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76  tion F to be inv
36af0 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65  oked with argume
36b00 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a  nt P whenever.**
36b10 20 20 20 20 20 20 20 20 20 20 61 20 74 72 61 6e            a tran
36b20 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 20  saction commits 
36b30 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
36b40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
36b50 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 32 7d 20 54  **.** {H12952} T
36b60 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  he [sqlite3_comm
36b70 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  it_hook(D,F,P)] 
36b80 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
36b90 73 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74  s the P argument
36ba0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f  .**          fro
36bb0 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  m the previous c
36bc0 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61 6d  all with the sam
36bd0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
36be0 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20  ection] D,.**   
36bf0 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 6f         or NULL o
36c00 6e 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  n the first call
36c10 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
36c20 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
36c30 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  ction D..**.** {
36c40 48 31 32 39 35 33 7d 20 45 61 63 68 20 63 61 6c  H12953} Each cal
36c50 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
36c60 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65  mmit_hook()] ove
36c70 72 77 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c  rwrites the call
36c80 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
36c90 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 70   registered by p
36ca0 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a  rior calls..**.*
36cb0 2a 20 7b 48 31 32 39 35 34 7d 20 49 66 20 74 68  * {H12954} If th
36cc0 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  e F argument to 
36cd0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
36ce0 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20  hook(D,F,P)] is 
36cf0 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  NULL.**         
36d00 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
36d10 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69   hook callback i
36d20 73 20 63 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e  s canceled and n
36d30 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  o callback.**   
36d40 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65         is invoke
36d50 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63  d when a transac
36d60 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a 2a 2a  tion commits..**
36d70 0a 2a 2a 20 7b 48 31 32 39 35 35 7d 20 49 66 20  .** {H12955} If 
36d80 74 68 65 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62  the commit callb
36d90 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
36da0 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20 63 6f  zero then the co
36db0 6d 6d 69 74 20 69 73 0a 2a 2a 20 20 20 20 20 20  mmit is.**      
36dc0 20 20 20 20 63 6f 6e 76 65 72 74 65 64 20 69 6e      converted in
36dd0 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  to a rollback..*
36de0 2a 0a 2a 2a 20 7b 48 31 32 39 36 31 7d 20 54 68  *.** {H12961} Th
36df0 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  e [sqlite3_rollb
36e00 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  ack_hook(D,F,P)]
36e10 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
36e20 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ters the.**     
36e30 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75       callback fu
36e40 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69  nction F to be i
36e50 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75  nvoked with argu
36e60 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a  ment P whenever.
36e70 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 72  **          a tr
36e80 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20  ansaction rolls 
36e90 62 61 63 6b 20 6f 6e 20 74 68 65 20 5b 64 61 74  back on the [dat
36ea0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36eb0 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ] D..**.** {H129
36ec0 36 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  62} The [sqlite3
36ed0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
36ee0 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
36ef0 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 0a 2a   returns the P.*
36f00 2a 20 20 20 20 20 20 20 20 20 20 61 72 67 75 6d  *          argum
36f10 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
36f20 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20  vious call with 
36f30 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20  the same.**     
36f40 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
36f50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72  onnection] D, or
36f60 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72   NULL on the fir
36f70 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  st call.**      
36f80 20 20 20 20 66 6f 72 20 61 20 70 61 72 74 69 63      for a partic
36f90 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 63 6f  ular database co
36fa0 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a  nnection D..**.*
36fb0 2a 20 7b 48 31 32 39 36 33 7d 20 45 61 63 68 20  * {H12963} Each 
36fc0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
36fd0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
36fe0 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65  ] overwrites the
36ff0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
37000 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64        registered
37010 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e   by prior calls.
37020 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 34 7d 20  .**.** {H12964} 
37030 49 66 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e  If the F argumen
37040 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f  t to [sqlite3_ro
37050 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c  llback_hook(D,F,
37060 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20  P)] is NULL.**  
37070 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65          then the
37080 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63   rollback hook c
37090 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65  allback is cance
370a0 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62  led and no callb
370b0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
370c0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
370d0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f  a transaction ro
370e0 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76 6f 69  lls back..*/.voi
370f0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  d *sqlite3_commi
37100 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  t_hook(sqlite3*,
37110 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
37120 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71  void*);.void *sq
37130 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
37140 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ook(sqlite3*, vo
37150 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76  id(*)(void *), v
37160 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
37170 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61  PI3REF: Data Cha
37180 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  nge Notification
37190 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39   Callbacks {H129
371a0 37 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a  70} <S60400>.**.
371b0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
371c0 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74  pdate_hook() int
371d0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
371e0 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
371f0 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
37200 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37210 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65  ction] identifie
37220 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
37230 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65  rgument.** to be
37240 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
37250 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74  r a row is updat
37260 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20  ed, inserted or 
37270 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  deleted..** Any 
37280 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
37290 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
372a0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
372b0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
372c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
372d0 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
372e0 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  en..**.** The se
372f0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
37300 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
37310 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e  e function to in
37320 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72  voke when a.** r
37330 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
37340 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
37350 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ed..** The first
37360 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
37370 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
37380 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
37390 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
373a0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
373b0 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65  ook()..** The se
373c0 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72  cond callback ar
373d0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
373e0 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d   [SQLITE_INSERT]
373f0 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  , [SQLITE_DELETE
37400 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
37410 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64  _UPDATE], depend
37420 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61  ing on the opera
37430 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64  tion that caused
37440 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
37450 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a   to be invoked..
37460 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64  ** The third and
37470 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
37480 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
37490 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65  k contain pointe
374a0 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  rs to the.** dat
374b0 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20  abase and table 
374c0 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  name containing 
374d0 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77  the affected row
374e0 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63  ..** The final c
374f0 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
37500 72 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 6f  r is the rowid o
37510 66 20 74 68 65 20 72 6f 77 2e 20 49 6e 20 74 68  f the row. In th
37520 65 20 63 61 73 65 20 6f 66 0a 2a 2a 20 61 6e 20  e case of.** an 
37530 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20  update, this is 
37540 74 68 65 20 72 6f 77 69 64 20 61 66 74 65 72 20  the rowid after 
37550 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73  the update takes
37560 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   place..**.** Th
37570 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73  e update hook is
37580 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65   not invoked whe
37590 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65  n internal syste
375a0 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20  m tables are.** 
375b0 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73  modified (i.e. s
375c0 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64  qlite_master and
375d0 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65   sqlite_sequence
375e0 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  )..**.** If anot
375f0 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73  her function was
37600 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69   previously regi
37610 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 72 67  stered, its pArg
37620 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74   value.** is ret
37630 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
37640 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  e NULL is return
37650 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
37660 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
37670 39 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  971} The [sqlite
37680 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
37690 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,P)] interface 
376a0 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
376b0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
376c0 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65  function F to be
376d0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 69   invoked with fi
376e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 50 20  rst parameter P 
376f0 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20  whenever.**     
37700 20 20 20 20 20 61 20 74 61 62 6c 65 20 72 6f 77       a table row
37710 20 69 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e   is modified, in
37720 73 65 72 74 65 64 2c 20 6f 72 20 64 65 6c 65 74  serted, or delet
37730 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ed on.**        
37740 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20    the [database 
37750 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
37760 2a 0a 2a 2a 20 7b 48 31 32 39 37 33 7d 20 54 68  *.** {H12973} Th
37770 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
37780 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  e_hook(D,F,P)] i
37790 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
377a0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20   the value.**   
377b0 20 20 20 20 20 20 20 6f 66 20 50 20 66 6f 72 20         of P for 
377c0 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
377d0 6c 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  l on the same [d
377e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
377f0 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20  on] D,.**       
37800 20 20 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 20 74     or NULL for t
37810 68 65 20 66 69 72 73 74 20 63 61 6c 6c 2e 0a 2a  he first call..*
37820 2a 0a 2a 2a 20 7b 48 31 32 39 37 35 7d 20 49 66  *.** {H12975} If
37830 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
37840 20 63 61 6c 6c 62 61 63 6b 20 46 20 69 6e 20 5b   callback F in [
37850 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
37860 6f 6f 6b 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20  ook(D,F,P)].**  
37870 20 20 20 20 20 20 20 20 69 73 20 4e 55 4c 4c 20          is NULL 
37880 74 68 65 6e 20 74 68 65 20 6e 6f 20 75 70 64 61  then the no upda
37890 74 65 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65  te callbacks are
378a0 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   made..**.** {H1
378b0 32 39 37 37 7d 20 45 61 63 68 20 63 61 6c 6c 20  2977} Each call 
378c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  to [sqlite3_upda
378d0 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  te_hook(D,F,P)] 
378e0 6f 76 65 72 72 69 64 65 73 20 70 72 69 6f 72 20  overrides prior 
378f0 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20  calls.**        
37900 20 20 74 6f 20 74 68 65 20 73 61 6d 65 20 69 6e    to the same in
37910 74 65 72 66 61 63 65 20 6f 6e 20 74 68 65 20 73  terface on the s
37920 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
37930 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
37940 2a 2a 20 7b 48 31 32 39 37 39 7d 20 54 68 65 20  ** {H12979} The 
37950 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c  update hook call
37960 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
37970 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
37980 6c 20 73 79 73 74 65 6d 0a 2a 2a 20 20 20 20 20  l system.**     
37990 20 20 20 20 20 74 61 62 6c 65 73 20 73 75 63 68       tables such
379a0 20 61 73 20 73 71 6c 69 74 65 5f 6d 61 73 74 65   as sqlite_maste
379b0 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
379c0 75 65 6e 63 65 20 61 72 65 20 6d 6f 64 69 66 69  uence are modifi
379d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 38  ed..**.** {H1298
379e0 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  1} The second pa
379f0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 75  rameter to the u
37a00 70 64 61 74 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  pdate callback.*
37a10 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6f 6e  *          is on
37a20 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53  e of [SQLITE_INS
37a30 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45  ERT], [SQLITE_DE
37a40 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LETE] or [SQLITE
37a50 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 20 20 20  _UPDATE],.**    
37a60 20 20 20 20 20 20 64 65 70 65 6e 64 69 6e 67 20        depending 
37a70 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
37a80 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
37a90 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20   callback to be 
37aa0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  invoked..**.** {
37ab0 48 31 32 39 38 33 7d 20 54 68 65 20 74 68 69 72  H12983} The thir
37ac0 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67  d and fourth arg
37ad0 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61  uments to the ca
37ae0 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70  llback contain p
37af0 6f 69 6e 74 65 72 73 0a 2a 2a 20 20 20 20 20 20  ointers.**      
37b00 20 20 20 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d      to zero-term
37b10 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
37b20 69 6e 67 73 20 77 68 69 63 68 20 61 72 65 20 74  ings which are t
37b30 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  he names of the.
37b40 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61  **          data
37b50 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 74  base and table t
37b60 68 61 74 20 69 73 20 62 65 69 6e 67 20 75 70 64  hat is being upd
37b70 61 74 65 64 2e 0a 0a 2a 2a 20 7b 48 31 32 39 38  ated...** {H1298
37b80 35 7d 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  5} The final cal
37b90 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
37ba0 69 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  is the rowid of 
37bb0 74 68 65 20 72 6f 77 20 61 66 74 65 72 0a 2a 2a  the row after.**
37bc0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 68            the ch
37bd0 61 6e 67 65 20 6f 63 63 75 72 73 2e 0a 2a 2f 0a  ange occurs..*/.
37be0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70  void *sqlite3_up
37bf0 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c  date_hook(.  sql
37c00 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  ite3*, .  void(*
37c10 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68  )(void *,int ,ch
37c20 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20  ar const *,char 
37c30 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f  const *,sqlite3_
37c40 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a  int64),.  void*.
37c50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37c60 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
37c70 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67  sable Shared Pag
37c80 65 72 20 43 61 63 68 65 20 7b 48 31 30 33 33 30  er Cache {H10330
37c90 7d 20 3c 53 33 30 39 30 30 3e 0a 2a 2a 20 4b 45  } <S30900>.** KE
37ca0 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20  YWORDS: {shared 
37cb0 63 61 63 68 65 7d 20 7b 73 68 61 72 65 64 20 63  cache} {shared c
37cc0 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a  ache mode}.**.**
37cd0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e   This routine en
37ce0 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
37cf0 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
37d00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
37d10 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
37d20 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  a data structure
37d30 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62  s between [datab
37d40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c  ase connection |
37d50 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a   connections].**
37d60 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
37d70 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69  abase. Sharing i
37d80 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
37d90 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
37da0 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65  e.** and disable
37db0 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
37dc0 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a  t is false..**.*
37dd0 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e 67 20  * Cache sharing 
37de0 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64  is enabled and d
37df0 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65  isabled for an e
37e00 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 20 7b  ntire process. {
37e10 45 4e 44 7d 0a 2a 2a 20 54 68 69 73 20 69 73 20  END}.** This is 
37e20 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53  a change as of S
37e30 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
37e40 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65  5.0. In prior ve
37e50 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
37e60 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73  ,.** sharing was
37e70 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
37e80 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68  bled for each th
37e90 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e  read separately.
37ea0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65  .**.** The cache
37eb0 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65   sharing mode se
37ec0 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66  t by this interf
37ed0 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20  ace effects all 
37ee0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  subsequent.** ca
37ef0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
37f00 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
37f10 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e  3_open_v2()], an
37f20 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  d [sqlite3_open1
37f30 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  6()]..** Existin
37f40 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  g database conne
37f50 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
37f60 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20  use the sharing 
37f70 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73  mode.** that was
37f80 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68   in effect at th
37f90 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65  e time they were
37fa0 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56   opened..**.** V
37fb0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61  irtual tables ca
37fc0 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69 74  nnot be used wit
37fd0 68 20 61 20 73 68 61 72 65 64 20 63 61 63 68 65  h a shared cache
37fe0 2e 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a  .  When shared.*
37ff0 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
38000 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ed, the [sqlite3
38010 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29  _create_module()
38020 5d 20 41 50 49 20 75 73 65 64 20 74 6f 20 72 65  ] API used to re
38030 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61  gister.** virtua
38040 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c  l tables will al
38050 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65  ways return an e
38060 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  rror..**.** This
38070 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
38080 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20   [SQLITE_OK] if 
38090 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73  shared cache was
380a0 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
380b0 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66  bled.** successf
380c0 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72  ully.  An [error
380d0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
380e0 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
380f0 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 65  .** Shared cache
38100 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
38110 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69  default. But thi
38120 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  s might change i
38130 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65  n.** future rele
38140 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ases of SQLite. 
38150 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
38160 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68  at care about sh
38170 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65  ared.** cache se
38180 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74  tting should set
38190 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a   it explicitly..
381a0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
381b0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 33 33 31 7d  :.**.** {H10331}
381c0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
381d0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
381e0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
381f0 65 64 5f 63 61 63 68 65 28 42 29 5d 0a 2a 2a 20  ed_cache(B)].** 
38200 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 65 6e           will en
38210 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
38220 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
38230 65 20 66 6f 72 20 61 6e 79 20 73 75 62 73 65 71  e for any subseq
38240 75 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20  uently.**       
38250 20 20 20 63 72 65 61 74 65 64 20 5b 64 61 74 61     created [data
38260 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
38270 20 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f   in the same pro
38280 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  cess..**.** {H10
38290 33 33 36 7d 20 57 68 65 6e 20 73 68 61 72 65 64  336} When shared
382a0 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
382b0 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d, the [sqlite3_
382c0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d  create_module()]
382d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
382e0 65 72 66 61 63 65 20 77 69 6c 6c 20 61 6c 77 61  erface will alwa
382f0 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  ys return an err
38300 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 33 33  or..**.** {H1033
38310 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
38320 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
38330 63 68 65 28 42 29 5d 20 69 6e 74 65 72 66 61 63  che(B)] interfac
38340 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
38350 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b        [SQLITE_OK
38360 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68  ] if shared cach
38370 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72  e was enabled or
38380 20 64 69 73 61 62 6c 65 64 20 73 75 63 63 65 73   disabled succes
38390 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  sfully..**.** {H
383a0 31 30 33 33 39 7d 20 53 68 61 72 65 64 20 63 61  10339} Shared ca
383b0 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  che is disabled 
383c0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69  by default..*/.i
383d0 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  nt sqlite3_enabl
383e0 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69  e_shared_cache(i
383f0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
38400 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f  3REF: Attempt To
38410 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72   Free Heap Memor
38420 79 20 7b 48 31 37 33 34 30 7d 20 3c 53 33 30 32  y {H17340} <S302
38430 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  20>.**.** The sq
38440 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
38450 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 65  mory() interface
38460 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65   attempts to fre
38470 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  e N bytes.** of 
38480 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64  heap memory by d
38490 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d  eallocating non-
384a0 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79  essential memory
384b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20   allocations.** 
384c0 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61  held by the data
384d0 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20 7b 45  base library. {E
384e0 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65 64  ND}  Memory used
384f0 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61   to cache databa
38500 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69  se.** pages to i
38510 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
38520 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  ce is an example
38530 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61   of non-essentia
38540 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 73 71 6c  l memory..** sql
38550 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
38560 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 68  ory() returns th
38570 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
38580 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64  s actually freed
38590 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74  ,.** which might
385a0 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73   be more or less
385b0 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74   than the amount
385c0 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a   requested..**.*
385d0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
385e0 0a 2a 2a 20 7b 48 31 37 33 34 31 7d 20 54 68 65  .** {H17341} The
385f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
38600 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 69 6e 74  e_memory(N)] int
38610 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
38620 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  to.**          f
38630 72 65 65 20 4e 20 62 79 74 65 73 20 6f 66 20 68  ree N bytes of h
38640 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65  eap memory by de
38650 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65  allocating non-e
38660 73 73 65 6e 74 69 61 6c 0a 2a 2a 20 20 20 20 20  ssential.**     
38670 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f       memory allo
38680 63 61 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20  cations held by 
38690 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62  the database lib
386a0 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  rary..**.** {H16
386b0 33 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  342} The [sqlite
386c0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
386d0 28 4e 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65  (N)] returns the
386e0 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20   number.**      
386f0 20 20 20 20 6f 66 20 62 79 74 65 73 20 61 63 74      of bytes act
38700 75 61 6c 6c 79 20 66 72 65 65 64 2c 20 77 68 69  ually freed, whi
38710 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65  ch might be more
38720 20 6f 72 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20   or less.**     
38730 20 20 20 20 20 74 68 61 6e 20 74 68 65 20 61 6d       than the am
38740 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a  ount requested..
38750 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
38760 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e  elease_memory(in
38770 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
38780 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69  REF: Impose A Li
38790 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65  mit On Heap Size
387a0 20 7b 48 31 37 33 35 30 7d 20 3c 53 33 30 32 32   {H17350} <S3022
387b0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
387c0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
387d0 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  imit() interface
387e0 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22   places a "soft"
387f0 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65   limit.** on the
38800 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20   amount of heap 
38810 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20  memory that may 
38820 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  be allocated by 
38830 53 51 4c 69 74 65 2e 0a 2a 2a 20 49 66 20 61 6e  SQLite..** If an
38840 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61   internal alloca
38850 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
38860 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63  d that would exc
38870 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20  eed the.** soft 
38880 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c  heap limit, [sql
38890 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
388a0 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ory()] is invoke
388b0 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65  d one or.** more
388c0 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75   times to free u
388d0 70 20 73 6f 6d 6