/ Hex Artifact Content
Login

Artifact dd72570543919552b62dcfbc24a93d8e5a46742e:


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 30 20 32 30 30 38 2f 30  n,v 1.380 2008/0
05f0: 37 2f 32 35 20 31 35 3a 33 39 3a 30 34 20 64 72  7/25 15:39:04 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 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
aa00: 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31  ion Routines {H1
aa10: 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e 0a 2a  0155} <S20120>.*
aa20: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
aa30: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
aa40: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
aa50: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
aa60: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
aa70: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
aa80: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
aa90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
aaa0: 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
aab0: 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
aac0: 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
aad0: 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
aae0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
aaf0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
ab00: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
ab10: 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
ab20: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
ab30: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
ab40: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
ab50: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
ab60: 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65 61 74  LLOC].  By creat
ab70: 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
ab80: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
ab90: 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
aba0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
abb0: 66 69 67 28 29 5d 20 64 75 72 69 6e 67 20 63 6f  fig()] during co
abc0: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 0a  nfiguration, an.
abd0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  ** application c
abe0: 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
abf0: 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
ac00: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
ac10: 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53 51 4c  ystem.** for SQL
ac20: 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
ac30: 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
ac40: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
ac50: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
ac60: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
ac70: 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  h a built-in mem
ac80: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
ac90: 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65 63 74  at is.** perfect
aca0: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
acb0: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
acc0: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
acd0: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
ace0: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
acf0: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
ad00: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
ad10: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
ad20: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
ad30: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
ad40: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
ad50: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
ad60: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
ad70: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
ad80: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
ad90: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
ada0: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
adb0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
adc0: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
add0: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
ade0: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
adf0: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
ae00: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
ae10: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
ae20: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
ae30: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
ae40: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
ae50: 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61 6e 64  lloc, xFree, and
ae60: 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64   xRealloc method
ae70: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
ae80: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
ae90: 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20 72 65  , free(), and re
aea0: 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69 6f 6e  alloc() function
aeb0: 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
aec0: 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  ard library..**.
aed0: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
aee0: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
aef0: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
af00: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
af10: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
af20: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
af30: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
af40: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
af50: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
af60: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
af70: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
af80: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
af90: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
afa0: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
afb0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
afc0: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
afd0: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
afe0: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
aff0: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
b000: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
b010: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
b020: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
b030: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
b040: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b050: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
b060: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
b070: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
b080: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
b090: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
b0a0: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
b0b0: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 0a   power of 2..**.
b0c0: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
b0d0: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
b0e0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
b0f0: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
b100: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
b110: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
b120: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
b130: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
b140: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
b150: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
b160: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
b170: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
b180: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
b190: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b1a0: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
b1b0: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
b1c0: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
b1d0: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
b1e0: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
b1f0: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
b200: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
b210: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
b220: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a 74 79  xShutdown..*/.ty
b230: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
b240: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
b250: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
b260: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
b270: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
b280: 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
b290: 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
b2a0: 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
b2b0: 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
b2c0: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
b2d0: 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
b2e0: 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
b2f0: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
b300: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
b310: 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
b320: 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
b330: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
b340: 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
b350: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
b360: 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
b370: 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
b380: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
b390: 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
b3a0: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
b3b0: 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
b3c0: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
b3d0: 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
b3e0: 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
b3f0: 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
b400: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
b410: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
b420: 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
b430: 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
b440: 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
b450: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
b460: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
b470: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
b480: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
b490: 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
b4a0: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
b4b0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
b4c0: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
b4d0: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31  tion Options {H1
b4e0: 30 31 36 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a  0160} <S20000>.*
b4f0: 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
b500: 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
b510: 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
b520: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
b530: 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
b540: 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
b550: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
b560: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
b570: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
b580: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
b590: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
b5a0: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
b5b0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
b5c0: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
b5d0: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
b5e0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
b5f0: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
b600: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
b610: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
b620: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
b630: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
b640: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
b650: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
b660: 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
b670: 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
b680: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
b690: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
b6a0: 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
b6b0: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
b6c0: 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
b6d0: 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
b6e0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
b6f0: 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
b700: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
b710: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
b720: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
b730: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
b740: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
b750: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
b760: 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e  on.  This option
b770: 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c   disables.** all
b780: 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75   mutexing and pu
b790: 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61  ts SQLite into a
b7a0: 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63   mode where it c
b7b0: 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a  an only be used.
b7c0: 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ** by a single t
b7d0: 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  hread.</dd>.**.*
b7e0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
b7f0: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
b800: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
b810: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
b820: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
b830: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  n.  This option 
b840: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
b850: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
b860: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
b870: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
b880: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
b890: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
b8a0: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
b8b0: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
b8c0: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
b8d0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
b8e0: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
b8f0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
b900: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
b910: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
b920: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
b930: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
b940: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
b950: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
b960: 69 72 6f 6e 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a  ironment.</dd>.*
b970: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
b980: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
b990: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
b9a0: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
b9b0: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
b9c0: 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f  ion.  This optio
b9d0: 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
b9e0: 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
b9f0: 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
ba00: 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
ba10: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
ba20: 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
ba30: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
ba40: 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
ba50: 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
ba60: 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
ba70: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
ba80: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
ba90: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
baa0: 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
bab0: 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
bac0: 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
bad0: 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
bae0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
baf0: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
bb00: 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
bb10: 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
bb20: 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
bb30: 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
bb40: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
bb50: 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
bb60: 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
bb70: 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
bb80: 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
bb90: 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
bba0: 2a 0a 2a 2a 20 3c 70 3e 54 68 69 73 20 63 6f 6e  *.** <p>This con
bbb0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
bbc0: 6e 20 6d 65 72 65 6c 79 20 73 65 74 73 20 74 68  n merely sets th
bbd0: 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
bbe0: 0a 2a 2a 20 62 65 68 61 76 69 6f 72 20 74 6f 20  .** behavior to 
bbf0: 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
bc00: 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f   to [database co
bc10: 6e 6e 65 63 74 69 6f 6e 73 5d 2e 20 20 49 6e 64  nnections].  Ind
bc20: 69 76 69 64 75 61 6c 0a 2a 2a 20 5b 64 61 74 61  ividual.** [data
bc30: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
bc40: 5d 20 63 61 6e 20 6f 76 65 72 72 69 64 65 20 74  ] can override t
bc50: 68 69 73 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75  his setting.** u
bc60: 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
bc70: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
bc80: 6c 61 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lag to [sqlite3_
bc90: 6f 70 65 6e 5f 76 32 28 29 5d 2e 3c 2f 70 3e 3c  open_v2()].</p><
bca0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
bcb0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
bcc0: 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
bcd0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
bce0: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
bcf0: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
bd00: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
bd10: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
bd20: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
bd30: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
bd40: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
bd50: 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
bd60: 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
bd70: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
bd80: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
bd90: 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
bda0: 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
bdb0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
bdc0: 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
bdd0: 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a   SQLite.</dd>.**
bde0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
bdf0: 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c  ONFIG_GETMALLOC<
be00: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
be10: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
be20: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
be30: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
be40: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
be50: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
be60: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
be70: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
be80: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
be90: 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
bea0: 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
beb0: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
bec0: 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
bed0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
bee0: 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70  ines..** This op
bef0: 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
bf00: 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
bf10: 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
bf20: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
bf30: 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
bf40: 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c  apper that simul
bf50: 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c  ations memory al
bf60: 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
bf70: 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65   or.** tracks me
bf80: 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20  mory usage, for 
bf90: 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a  example.</dd>.**
bfa0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
bfb0: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
bfc0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
bfd0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
bfe0: 6e 67 6c 65 20 62 6f 6f 6c 65 61 6e 20 61 72 67  ngle boolean arg
bff0: 75 6d 65 6e 74 20 77 68 69 63 68 20 65 6e 61 62  ument which enab
c000: 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 0a  les or disables.
c010: 2a 2a 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  ** the collectio
c020: 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
c030: 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
c040: 73 2e 20 20 57 68 65 6e 20 64 69 73 61 62 6c 65  s.  When disable
c050: 64 2c 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  d, the.** follow
c060: 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
c070: 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
c080: 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
c090: 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
c0a0: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
c0b0: 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
c0c0: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
c0d0: 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
c0e0: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
c0f0: 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
c100: 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  mit()].**   <li>
c110: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
c120: 73 74 61 74 75 73 28 29 0a 2a 2a 20 20 20 3c 2f  status().**   </
c130: 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ul>.** </dd>.**.
c140: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
c150: 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74  NFIG_SCRATCH</dt
c160: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
c170: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
c180: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
c190: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
c1a0: 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
c1b0: 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
c1c0: 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65    There are thre
c1d0: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20  e arguments:  A 
c1e0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
c1f0: 65 6d 6f 72 79 2c 20 74 68 65 0a 2a 2a 20 73 69  emory, the.** si
c200: 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
c210: 63 68 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20  ch buffer (sz), 
c220: 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
c230: 66 20 62 75 66 66 65 72 73 20 28 4e 29 2e 20 20  f buffers (N).  
c240: 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65  The sz.** argume
c250: 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c  nt must be a mul
c260: 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68 65  tiple of 16. The
c270: 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65   first.** argume
c280: 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20  nt should point 
c290: 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  to an allocation
c2a0: 20 6f 66 20 61 74 20 6c 65 61 73 74 20 28 73 7a   of at least (sz
c2b0: 2b 34 29 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d  +4)*N bytes of m
c2c0: 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65  emory..** SQLite
c2d0: 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72   will use no mor
c2e0: 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74  e than one scrat
c2f0: 63 68 20 62 75 66 66 65 72 20 61 74 20 6f 6e 63  ch buffer at onc
c300: 65 20 70 65 72 20 74 68 72 65 61 64 2c 20 73 6f  e per thread, so
c310: 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20  .** N should be 
c320: 73 65 74 20 74 6f 20 74 68 65 20 65 78 70 65 63  set to the expec
c330: 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ted maximum numb
c340: 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 20 20  er of threads.  
c350: 54 68 65 20 73 7a 0a 2a 2a 20 70 61 72 61 6d 65  The sz.** parame
c360: 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 36 20  ter should be 6 
c370: 74 69 6d 65 73 20 74 68 65 20 73 69 7a 65 20 6f  times the size o
c380: 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
c390: 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65  tabase page size
c3a0: 2e 0a 2a 2a 20 53 63 72 61 74 63 68 20 62 75 66  ..** Scratch buf
c3b0: 66 65 72 73 20 61 72 65 20 75 73 65 64 20 61 73  fers are used as
c3c0: 20 70 61 72 74 20 6f 66 20 74 68 65 20 62 74 72   part of the btr
c3d0: 65 65 20 62 61 6c 61 6e 63 65 20 6f 70 65 72 61  ee balance opera
c3e0: 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54 68 65  tion.  If.** The
c3f0: 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 72 20   btree balancer 
c400: 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c  needs additional
c410: 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
c420: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
c430: 62 79 0a 2a 2a 20 73 63 72 61 74 63 68 20 62 75  by.** scratch bu
c440: 66 66 65 72 73 20 6f 72 20 69 66 20 6e 6f 20 73  ffers or if no s
c450: 63 72 61 74 63 68 20 62 75 66 66 65 72 20 73 70  cratch buffer sp
c460: 61 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64  ace is specified
c470: 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
c480: 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
c490: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f 20 6f  3_malloc()] to o
c4a0: 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  btain the memory
c4b0: 20 69 74 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a   it needs.</dd>.
c4c0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
c4d0: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
c4e0: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  E</dt>.** <dd>Th
c4f0: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
c500: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
c510: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
c520: 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
c530: 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  or.** the databa
c540: 73 65 20 70 61 67 65 20 63 61 63 68 65 2e 20 20  se page cache.  
c550: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
c560: 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69  arguments: A poi
c570: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 6d  nter to the.** m
c580: 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20  emory, the size 
c590: 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66  of each page buf
c5a0: 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68  fer (sz), and th
c5b0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65  e number of page
c5c0: 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a  s (N)..** The sz
c5d0: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
c5e0: 65 20 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f  e a power of two
c5f0: 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64   between 512 and
c600: 20 33 32 37 36 38 2e 20 20 54 68 65 20 66 69 72   32768.  The fir
c610: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  st.** argument s
c620: 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61  hould point to a
c630: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20  n allocation of 
c640: 61 74 20 6c 65 61 73 74 20 28 73 7a 2b 34 29 2a  at least (sz+4)*
c650: 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
c660: 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  y..** SQLite wil
c670: 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  l use the memory
c680: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
c690: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
c6a0: 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a  to satisfy its.*
c6b0: 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66  * memory needs f
c6c0: 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70  or the first N p
c6d0: 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64  ages that it add
c6e0: 73 20 74 6f 20 63 61 63 68 65 2e 20 20 49 66 20  s to cache.  If 
c6f0: 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61  additional.** pa
c700: 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
c710: 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64  is needed beyond
c720: 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
c730: 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e  d by this option
c740: 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
c750: 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
c760: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20  3_malloc()] for 
c770: 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73  the additional s
c780: 74 6f 72 61 67 65 20 73 70 61 63 65 2e 3c 2f 64  torage space.</d
c790: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
c7a0: 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
c7b0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
c7c0: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
c7d0: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
c7e0: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
c7f0: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
c800: 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
c810: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
c820: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20  llocation needs 
c830: 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
c840: 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20  vided.** for by 
c850: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
c860: 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c  CRATCH] and [SQL
c870: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
c880: 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  ACHE]..** There 
c890: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
c8a0: 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  nts: A pointer t
c8b0: 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68  o the memory, th
c8c0: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
c8d0: 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
c8e0: 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
c8f0: 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
c900: 61 74 69 6f 6e 20 73 69 7a 65 2e 20 20 49 66 0a  ation size.  If.
c910: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  ** the first poi
c920: 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
c930: 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
c940: 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
c950: 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
c960: 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
c970: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
c980: 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
c990: 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
c9a0: 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
c9b0: 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
c9c0: 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
c9d0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
c9e0: 20 20 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f    If the.** memo
c9f0: 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
ca00: 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65  t NULL and eithe
ca10: 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
ca20: 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20  _MEMSYS3] or.** 
ca30: 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
ca40: 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69  EMSYS5] are defi
ca50: 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c  ned, then the al
ca60: 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
ca70: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
ca80: 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
ca90: 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
caa0: 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
cab0: 69 6f 6e 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a  ion needs.</dd>.
cac0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
cad0: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64  _CONFIG_MUTEX</d
cae0: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
caf0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
cb00: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
cb10: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
cb20: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
cb30: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
cb40: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
cb50: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
cb60: 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
cb70: 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
cb80: 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
cb90: 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
cba0: 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
cbb0: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f  .** the mutex ro
cbc0: 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
cbd0: 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a  o SQLite.</dd>.*
cbe0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
cbf0: 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
cc00: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
cc10: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
cc20: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
cc30: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
cc40: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
cc50: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
cc60: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
cc70: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
cc80: 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
cc90: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
cca0: 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
ccb0: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
ccc0: 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
ccd0: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
cce0: 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
ccf0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
cd00: 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
cd10: 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
cd20: 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
cd30: 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
cd40: 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
cd50: 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
cd60: 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
cd70: 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
cd80: 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c  g, for example.<
cd90: 2f 64 64 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dd>.*/.#define 
cda0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
cdb0: 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
cdc0: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
cdd0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
cde0: 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
cdf0: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
ce00: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
ce10: 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
ce20: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
ce30: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
ce40: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
ce50: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
ce60: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
ce70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
ce80: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
ce90: 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
cea0: 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
ceb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
cec0: 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
ced0: 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
cee0: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
cef0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cf00: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
cf10: 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
cf20: 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
cf30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
cf40: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
cf50: 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
cf60: 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
cf70: 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
cf80: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
cf90: 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
cfa0: 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
cfb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
cfc0: 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
cfd0: 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
cfe0: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
cff0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d000: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
d010: 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
d020: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
d030: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
d040: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
d050: 4e 4b 41 4c 4c 4f 43 20 20 20 31 32 20 20 2f 2a  NKALLOC   12  /*
d060: 20 69 6e 74 20 74 68 72 65 73 68 6f 6c 64 20 2a   int threshold *
d070: 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
d080: 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
d090: 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
d0a0: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 32  esult Codes {H12
d0b0: 32 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  200} <S10700>.**
d0c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
d0d0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
d0e0: 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
d0f0: 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
d100: 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
d110: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
d120: 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
d130: 4c 69 74 65 2e 20 54 68 65 20 65 78 74 65 6e 64  Lite. The extend
d140: 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
d150: 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
d160: 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
d170: 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
d180: 69 62 69 6c 69 74 79 20 63 6f 6e 73 69 64 65 72  ibility consider
d190: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ations..**.** IN
d1a0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
d1b0: 7b 48 31 32 32 30 31 7d 20 45 61 63 68 20 6e 65  {H12201} Each ne
d1c0: 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  w [database conn
d1d0: 65 63 74 69 6f 6e 5d 20 73 68 61 6c 6c 20 68 61  ection] shall ha
d1e0: 76 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ve the.**       
d1f0: 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73     [extended res
d200: 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75  ult codes] featu
d210: 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
d220: 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  efault..**.** {H
d230: 31 32 32 30 32 7d 20 54 68 65 20 5b 73 71 6c 69  12202} The [sqli
d240: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
d250: 75 6c 74 5f 63 6f 64 65 73 28 44 2c 46 29 5d 20  ult_codes(D,F)] 
d260: 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
d270: 65 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20  enable.**       
d280: 20 20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73     [extended res
d290: 75 6c 74 20 63 6f 64 65 73 5d 20 66 6f 72 20 74  ult codes] for t
d2a0: 68 65 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f  he  [database co
d2b0: 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20  nnection] D.**  
d2c0: 20 20 20 20 20 20 20 20 69 66 20 74 68 65 20 46          if the F
d2d0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 72   parameter is tr
d2e0: 75 65 2c 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ue, or disable t
d2f0: 68 65 6d 20 69 66 20 46 20 69 73 20 66 61 6c 73  hem if F is fals
d300: 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
d310: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
d320: 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
d330: 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
d340: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
d350: 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
d360: 20 7b 48 31 32 32 32 30 7d 20 3c 53 31 30 37 30   {H12220} <S1070
d370: 30 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 65 6e  0>.**.** Each en
d380: 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65  try in an SQLite
d390: 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69   table has a uni
d3a0: 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  que 64-bit signe
d3b0: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79  d.** integer key
d3c0: 20 63 61 6c 6c 65 64 20 74 68 65 20 22 72 6f 77   called the "row
d3d0: 69 64 22 2e 20 54 68 65 20 72 6f 77 69 64 20 69  id". The rowid i
d3e0: 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62  s always availab
d3f0: 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65  le.** as an unde
d400: 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61  clared column na
d410: 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20  med ROWID, OID, 
d420: 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f  or _ROWID_ as lo
d430: 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e  ng as those.** n
d440: 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73  ames are not als
d450: 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63  o used by explic
d460: 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
d470: 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65  lumns. If.** the
d480: 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
d490: 75 6d 6e 20 6f 66 20 74 79 70 65 20 49 4e 54 45  umn of type INTE
d4a0: 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 20  GER PRIMARY KEY 
d4b0: 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
d4c0: 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
d4d0: 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
d4e0: 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  id..**.** This r
d4f0: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
d500: 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20  he rowid of the 
d510: 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
d520: 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54  uccessful INSERT
d530: 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
d540: 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74  se from the [dat
d550: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d560: 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
d570: 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 49 66 20  t argument.  If 
d580: 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e  no successful IN
d590: 53 45 52 54 73 0a 2a 2a 20 68 61 76 65 20 65 76  SERTs.** have ev
d5a0: 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
d5b0: 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e  hat database con
d5c0: 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73  nection, zero is
d5d0: 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
d5e0: 20 49 66 20 61 6e 20 49 4e 53 45 52 54 20 6f 63   If an INSERT oc
d5f0: 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
d600: 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20  igger, then the 
d610: 72 6f 77 69 64 20 6f 66 20 74 68 65 20 69 6e 73  rowid of the ins
d620: 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20  erted.** row is 
d630: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
d640: 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67   routine as long
d650: 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
d660: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42  is running..** B
d670: 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67  ut once the trig
d680: 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20  ger terminates, 
d690: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
d6a0: 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69  ed by this routi
d6b0: 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f  ne.** reverts to
d6c0: 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20   the last value 
d6d0: 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65 20  inserted before 
d6e0: 74 68 65 20 74 72 69 67 67 65 72 20 66 69 72 65  the trigger fire
d6f0: 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 49 4e 53 45  d..**.** An INSE
d700: 52 54 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  RT that fails du
d710: 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
d720: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
d730: 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
d740: 75 6c 20 49 4e 53 45 52 54 20 61 6e 64 20 64 6f  ul INSERT and do
d750: 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
d760: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
d770: 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
d780: 69 6e 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52  ine.  Thus INSER
d790: 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
d7a0: 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
d7b0: 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
d7c0: 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
d7d0: 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
d7e0: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
d7f0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
d800: 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
d810: 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
d820: 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e  ion fails.  When
d830: 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
d840: 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
d850: 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
d860: 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
d870: 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
d880: 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
d890: 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
d8a0: 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
d8b0: 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
d8c0: 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
d8d0: 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
d8e0: 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
d8f0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
d900: 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
d910: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
d920: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
d930: 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65   For the purpose
d940: 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
d950: 65 2c 20 61 6e 20 49 4e 53 45 52 54 20 69 73 20  e, an INSERT is 
d960: 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
d970: 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
d980: 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
d990: 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
d9a0: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   back..**.** INV
d9b0: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
d9c0: 48 31 32 32 32 31 7d 20 54 68 65 20 5b 73 71 6c  H12221} The [sql
d9d0: 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
d9e0: 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74 69  _rowid()] functi
d9f0: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 72  on returns the r
da00: 6f 77 69 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  owid.**         
da10: 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   of the most rec
da20: 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 49  ent successful I
da30: 4e 53 45 52 54 20 70 65 72 66 6f 72 6d 65 64 20  NSERT performed 
da40: 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  on the same.**  
da50: 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
da60: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
da70: 64 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  d within the sam
da80: 65 20 6f 72 20 68 69 67 68 65 72 20 6c 65 76 65  e or higher leve
da90: 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 72  l.**          tr
daa0: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f  igger context, o
dab0: 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20  r zero if there 
dac0: 68 61 76 65 20 62 65 65 6e 20 6e 6f 20 71 75 61  have been no qua
dad0: 6c 69 66 79 69 6e 67 20 69 6e 73 65 72 74 73 2e  lifying inserts.
dae0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32 33 7d 20  .**.** {H12223} 
daf0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  The [sqlite3_las
db00: 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
db10: 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ] function retur
db20: 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
db30: 20 20 20 73 61 6d 65 20 76 61 6c 75 65 20 77 68     same value wh
db40: 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
db50: 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 20  he same trigger 
db60: 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20 20 20 20  context.**      
db70: 20 20 20 20 69 6d 6d 65 64 69 61 74 65 6c 79 20      immediately 
db80: 62 65 66 6f 72 65 20 61 6e 64 20 61 66 74 65 72  before and after
db90: 20 61 20 52 4f 4c 4c 42 41 43 4b 2e 0a 2a 2a 0a   a ROLLBACK..**.
dba0: 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
dbb0: 2a 2a 0a 2a 2a 20 7b 41 31 32 32 33 32 7d 20 49  **.** {A12232} I
dbc0: 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
dbd0: 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
dbe0: 65 77 20 49 4e 53 45 52 54 20 6f 6e 20 74 68 65  ew INSERT on the
dbf0: 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   same.**        
dc00: 20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65    database conne
dc10: 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
dc20: 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
dc30: 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
dc40: 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69            functi
dc50: 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
dc60: 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
dc70: 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72  he last insert r
dc80: 6f 77 69 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  owid,.**        
dc90: 20 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65    then the value
dca0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
dcb0: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
dcc0: 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
dcd0: 20 20 20 20 20 20 20 20 20 20 75 6e 70 72 65 64            unpred
dce0: 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
dcf0: 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
dd00: 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
dd10: 65 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20  e new.**        
dd20: 20 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f    last insert ro
dd30: 77 69 64 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  wid..*/.sqlite3_
dd40: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
dd50: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
dd60: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
dd70: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
dd80: 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
dd90: 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48  Rows Modified {H
dda0: 31 32 32 34 30 7d 20 3c 53 31 30 36 30 30 3e 0a  12240} <S10600>.
ddb0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
ddc0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
ddd0: 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
dde0: 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
ddf0: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20  e changed.** or 
de00: 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
de10: 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
de20: 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
de30: 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
de40: 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  .** on the [data
de50: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
de60: 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
de70: 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
de80: 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68 61 6e 67  r..** Only chang
de90: 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65  es that are dire
dea0: 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62  ctly specified b
deb0: 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50  y the INSERT, UP
dec0: 44 41 54 45 2c 0a 2a 2a 20 6f 72 20 44 45 4c 45  DATE,.** or DELE
ded0: 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  TE statement are
dee0: 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
def0: 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
df00: 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
df10: 72 73 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  rs are not count
df20: 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c  ed. Use the [sql
df30: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
df40: 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a  es()] function.*
df50: 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  * to find the to
df60: 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
df70: 61 6e 67 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  anges including 
df80: 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
df90: 79 20 74 72 69 67 67 65 72 73 2e 0a 2a 2a 0a 2a  y triggers..**.*
dfa0: 2a 20 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22  * A "row change"
dfb0: 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20   is a change to 
dfc0: 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
dfd0: 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a  a single table.*
dfe0: 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49  * caused by an I
dff0: 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f  NSERT, DELETE, o
e000: 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65  r UPDATE stateme
e010: 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a  nt.  Rows that.*
e020: 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73  * are changed as
e030: 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66   side effects of
e040: 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
e050: 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a  int resolution,.
e060: 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f  ** rollback, ABO
e070: 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 44  RT processing, D
e080: 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72 20 62 79  ROP TABLE, or by
e090: 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   any other.** me
e0a0: 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20  chanisms do not 
e0b0: 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20  count as direct 
e0c0: 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a  row changes..**.
e0d0: 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f  ** A "trigger co
e0e0: 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70  ntext" is a scop
e0f0: 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74  e of execution t
e100: 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a  hat begins and.*
e110: 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20  * ends with the 
e120: 73 63 72 69 70 74 20 6f 66 20 61 20 74 72 69 67  script of a trig
e130: 67 65 72 2e 20 20 4d 6f 73 74 20 53 51 4c 20 73  ger.  Most SQL s
e140: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
e150: 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69   evaluated outsi
e160: 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65  de of any trigge
e170: 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20  r.  This is the 
e180: 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74  "top level".** t
e190: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20  rigger context. 
e1a0: 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69   If a trigger fi
e1b0: 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  res from the top
e1c0: 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77   level, a.** new
e1d0: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
e1e0: 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20   is entered for 
e1f0: 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20  the duration of 
e200: 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67  that one.** trig
e210: 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72  ger.  Subtrigger
e220: 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74  s create subcont
e230: 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64  exts for their d
e240: 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 43  uration..**.** C
e250: 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
e260: 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  exec()] or [sqli
e270: 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75  te3_step()] recu
e280: 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20  rsively does.** 
e290: 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77  not create a new
e2a0: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
e2b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  ..**.** This fun
e2c0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
e2d0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65  e number of dire
e2e0: 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69  ct row changes i
e2f0: 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65  n the.** most re
e300: 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
e310: 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73  ATE, or DELETE s
e320: 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
e330: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67  the same.** trig
e340: 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
e350: 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e 20 63 61  ** Thus, when ca
e360: 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
e370: 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
e380: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
e390: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
e3a0: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
e3b0: 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
e3c0: 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
e3d0: 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
e3e0: 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
e3f0: 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 57 69  e top level.  Wi
e400: 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
e410: 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
e420: 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
e430: 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
e440: 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
e450: 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
e460: 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
e470: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
e480: 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
e490: 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
e4a0: 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
e4b0: 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
e4c0: 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
e4d0: 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
e4e0: 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
e4f0: 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
e500: 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
e510: 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
e520: 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
e530: 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
e540: 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a 2a  r own context..*
e550: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c  *.** SQLite impl
e560: 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61  ements the comma
e570: 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  nd "DELETE FROM 
e580: 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61  table" without a
e590: 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a   WHERE clause.**
e5a0: 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64   by dropping and
e5b0: 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20   recreating the 
e5c0: 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73  table.  (This is
e5d0: 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61   much faster tha
e5e0: 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75  n going.** throu
e5f0: 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20  gh and deleting 
e600: 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65  individual eleme
e610: 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62  nts from the tab
e620: 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66  le.)  Because of
e630: 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a   this.** optimiz
e640: 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74  ation, the delet
e650: 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20  ions in "DELETE 
e660: 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20  FROM table" are 
e670: 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  not row changes 
e680: 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  and.** will not 
e690: 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68  be counted by th
e6a0: 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
e6b0: 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  s() or [sqlite3_
e6c0: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
e6d0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72  .** functions, r
e6e0: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
e6f0: 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65   number of eleme
e700: 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72  nts that were or
e710: 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74  iginally.** in t
e720: 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65  he table.  To ge
e730: 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f  t an accurate co
e740: 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  unt of the numbe
e750: 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65  r of rows delete
e760: 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54  d, use.** "DELET
e770: 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45  E FROM table WHE
e780: 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a  RE 1" instead..*
e790: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
e7a0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 31 7d 20  .**.** {H12241} 
e7b0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  The [sqlite3_cha
e7c0: 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e  nges()] function
e7d0: 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 74 68   shall return th
e7e0: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20  e number of.**  
e7f0: 20 20 20 20 20 20 20 20 72 6f 77 20 63 68 61 6e          row chan
e800: 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 68  ges caused by th
e810: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
e820: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a  SERT, UPDATE,.**
e830: 20 20 20 20 20 20 20 20 20 20 6f 72 20 44 45 4c            or DEL
e840: 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e  ETE statement on
e850: 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
e860: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e  se connection an
e870: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  d.**          wi
e880: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  thin the same or
e890: 20 68 69 67 68 65 72 20 74 72 69 67 67 65 72 20   higher trigger 
e8a0: 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f  context, or zero
e8b0: 20 69 66 20 74 68 65 72 65 20 68 61 76 65 0a 2a   if there have.*
e8c0: 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 62  *          not b
e8d0: 65 65 6e 20 61 6e 79 20 71 75 61 6c 69 66 79 69  een any qualifyi
e8e0: 6e 67 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a  ng row changes..
e8f0: 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 33 7d 20 53  **.** {H12243} S
e900: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74 68 65  tatements of the
e910: 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20 46 52   form "DELETE FR
e920: 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20 77 69  OM tablename" wi
e930: 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20  th no.**        
e940: 20 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 73    WHERE clause s
e950: 68 61 6c 6c 20 63 61 75 73 65 20 73 75 62 73 65  hall cause subse
e960: 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
e970: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
e980: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 74  te3_changes()] t
e990: 6f 20 72 65 74 75 72 6e 20 7a 65 72 6f 2c 20 72  o return zero, r
e9a0: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
e9b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
e9c0: 62 65 72 20 6f 66 20 72 6f 77 73 20 6f 72 69 67  ber of rows orig
e9d0: 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65 20 74 61  inally in the ta
e9e0: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  ble..**.** ASSUM
e9f0: 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
ea00: 31 32 32 35 32 7d 20 49 66 20 61 20 73 65 70 61  12252} If a sepa
ea10: 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
ea20: 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
ea30: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
ea40: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  onnection.**    
ea50: 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c        while [sql
ea60: 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
ea70: 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
ea80: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
ea90: 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ed.**          i
eaa0: 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
eab0: 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
eac0: 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
ead0: 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
eae0: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
eaf0: 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
eb00: 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
eb10: 66 69 65 64 20 7b 48 31 32 32 36 30 7d 20 3c 53  fied {H12260} <S
eb20: 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  10600>.**.** Thi
eb30: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
eb40: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
eb50: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
eb60: 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c 0a 2a  sed by INSERT,.*
eb70: 2a 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  * UPDATE or DELE
eb80: 54 45 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69  TE statements si
eb90: 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73  nce the [databas
eba0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61  e connection] wa
ebb0: 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65  s opened..** The
ebc0: 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64 65 73 20   count includes 
ebd0: 61 6c 6c 20 63 68 61 6e 67 65 73 20 66 72 6f 6d  all changes from
ebe0: 20 61 6c 6c 20 74 72 69 67 67 65 72 20 63 6f 6e   all trigger con
ebf0: 74 65 78 74 73 2e 20 20 48 6f 77 65 76 65 72 2c  texts.  However,
ec00: 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f  .** the count do
ec10: 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
ec20: 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69  hanges used to i
ec30: 6d 70 6c 65 6d 65 6e 74 20 52 45 50 4c 41 43 45  mplement REPLACE
ec40: 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a   constraints,.**
ec50: 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72   do rollbacks or
ec60: 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
ec70: 67 2c 20 6f 72 20 44 52 4f 50 20 74 61 62 6c 65  g, or DROP table
ec80: 20 70 72 6f 63 65 73 73 69 6e 67 2e 0a 2a 2a 20   processing..** 
ec90: 54 68 65 20 63 68 61 6e 67 65 73 20 61 72 65 20  The changes are 
eca0: 63 6f 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20  counted as soon 
ecb0: 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
ecc0: 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d   that makes them
ecd0: 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64   is.** completed
ece0: 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65   (when the state
ecf0: 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69 73 20 70  ment handle is p
ed00: 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
ed10: 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
ed20: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
ed30: 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51  ze()])..**.** SQ
ed40: 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
ed50: 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c  the command "DEL
ed60: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
ed70: 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20  without a WHERE 
ed80: 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f  clause.** by dro
ed90: 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61  pping and recrea
eda0: 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20  ting the table. 
edb0: 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66   (This is much f
edc0: 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67  aster than going
edd0: 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20  .** through and 
ede0: 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64  deleting individ
edf0: 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f  ual elements fro
ee00: 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42  m the table.)  B
ee10: 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a  ecause of this.*
ee20: 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20  * optimization, 
ee30: 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e  the deletions in
ee40: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
ee50: 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77  ble" are not row
ee60: 20 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20   changes and.** 
ee70: 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e  will not be coun
ee80: 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
ee90: 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20  e3_changes() or 
eea0: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
eeb0: 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e  hanges()].** fun
eec0: 63 74 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65  ctions, regardle
eed0: 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ss of the number
eee0: 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61   of elements tha
eef0: 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c  t were originall
ef00: 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61 62 6c  y.** in the tabl
ef10: 65 2e 20 20 54 6f 20 67 65 74 20 61 6e 20 61 63  e.  To get an ac
ef20: 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20  curate count of 
ef30: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
ef40: 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a  ws deleted, use.
ef50: 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  ** "DELETE FROM 
ef60: 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69  table WHERE 1" i
ef70: 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 53 65  nstead..**.** Se
ef80: 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
ef90: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
efa0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
efb0: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
efc0: 2a 20 7b 48 31 32 32 36 31 7d 20 54 68 65 20 5b  * {H12261} The [
efd0: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
efe0: 61 6e 67 65 73 28 29 5d 20 72 65 74 75 72 6e 73  anges()] returns
eff0: 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
f000: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  r.**          of
f010: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
f020: 73 65 64 20 62 79 20 49 4e 53 45 52 54 2c 20 55  sed by INSERT, U
f030: 50 44 41 54 45 2c 20 61 6e 64 2f 6f 72 20 44 45  PDATE, and/or DE
f040: 4c 45 54 45 0a 2a 2a 20 20 20 20 20 20 20 20 20  LETE.**         
f050: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 74   statements on t
f060: 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
f070: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 69  e connection], i
f080: 6e 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 20 20  n any.**        
f090: 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78    trigger contex
f0a0: 74 2c 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  t, since the dat
f0b0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f0c0: 20 77 61 73 20 63 72 65 61 74 65 64 2e 0a 2a 2a   was created..**
f0d0: 0a 2a 2a 20 7b 48 31 32 32 36 33 7d 20 53 74 61  .** {H12263} Sta
f0e0: 74 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66  tements of the f
f0f0: 6f 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  orm "DELETE FROM
f100: 20 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68   tablename" with
f110: 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   no.**          
f120: 57 48 45 52 45 20 63 6c 61 75 73 65 20 73 68 61  WHERE clause sha
f130: 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  ll not change th
f140: 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
f150: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20  .**          by 
f160: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
f170: 68 61 6e 67 65 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a  hanges()]..**.**
f180: 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a   ASSUMPTIONS:.**
f190: 0a 2a 2a 20 7b 41 31 32 32 36 34 7d 20 49 66 20  .** {A12264} If 
f1a0: 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
f1b0: 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
f1c0: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
f1d0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
f1e0: 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 6c  **          whil
f1f0: 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
f200: 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
f210: 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
f220: 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20  value.**        
f230: 20 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e    returned is un
f240: 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
f250: 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
f260: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
f270: 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
f280: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
f290: 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
f2a0: 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
f2b0: 67 20 51 75 65 72 79 20 7b 48 31 32 32 37 30 7d  g Query {H12270}
f2c0: 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S30500>.**.** 
f2d0: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
f2e0: 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
f2f0: 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
f300: 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
f310: 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
f320: 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
f330: 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
f340: 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
f350: 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
f360: 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
f370: 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
f380: 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
f390: 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
f3a0: 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
f3b0: 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
f3c0: 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
f3d0: 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
f3e0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ly..**.** It is 
f3f0: 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
f400: 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
f410: 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
f420: 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
f430: 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
f440: 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
f450: 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
f460: 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
f470: 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
f480: 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
f490: 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
f4a0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
f4b0: 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
f4c0: 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
f4d0: 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
f4e0: 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
f4f0: 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  rns..**.** If an
f500: 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
f510: 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
f520: 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
f530: 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
f540: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
f550: 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
f560: 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
f570: 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
f580: 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
f590: 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
f5a0: 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
f5b0: 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  etion..**.** An 
f5c0: 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
f5d0: 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
f5e0: 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
f5f0: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
f600: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74 65  ..** If the inte
f610: 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
f620: 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
f630: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
f640: 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
f650: 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
f660: 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
f670: 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
f680: 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
f690: 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
f6a0: 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
f6b0: 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  y..**.** A call 
f6c0: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
f6d0: 72 75 70 74 28 29 20 68 61 73 20 6e 6f 20 65 66  rupt() has no ef
f6e0: 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
f6f0: 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
f700: 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
f710: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
f720: 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
f730: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
f740: 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 31 7d 20 54  **.** {H12271} T
f750: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  he [sqlite3_inte
f760: 72 72 75 70 74 28 29 5d 20 69 6e 74 65 72 66 61  rrupt()] interfa
f770: 63 65 20 77 69 6c 6c 20 66 6f 72 63 65 20 61 6c  ce will force al
f780: 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20  l running.**    
f790: 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d        SQL statem
f7a0: 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
f7b0: 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 64 61  with the same da
f7c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f7d0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  n.**          to
f7e0: 20 68 61 6c 74 20 61 66 74 65 72 20 70 72 6f 63   halt after proc
f7f0: 65 73 73 69 6e 67 20 61 74 20 6d 6f 73 74 20 6f  essing at most o
f800: 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 6f  ne additional ro
f810: 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
f820: 20 7b 48 31 32 32 37 32 7d 20 41 6e 79 20 53 51   {H12272} Any SQ
f830: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
f840: 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
f850: 62 79 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  by [sqlite3_inte
f860: 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20  rrupt()].**     
f870: 20 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72 6e       will return
f880: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
f890: 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  PT]..**.** ASSUM
f8a0: 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
f8b0: 31 32 32 37 39 7d 20 49 66 20 74 68 65 20 64 61  12279} If the da
f8c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f8d0: 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
f8e0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
f8f0: 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  t()].**         
f900: 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
f910: 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
f920: 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
f930: 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
f940: 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65  interrupt(sqlite
f950: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
f960: 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
f970: 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
f980: 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20  ent Is Complete 
f990: 7b 48 31 30 35 31 30 7d 20 3c 53 37 30 32 30 30  {H10510} <S70200
f9a0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
f9b0: 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
f9c0: 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69  l for command-li
f9d0: 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
f9e0: 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
f9f0: 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
fa00: 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
fa10: 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 20 61 20  form complete a 
fa20: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
fa30: 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
fa40: 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
fa50: 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
fa60: 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
fa70: 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
fa80: 73 69 6e 67 2e 20 20 54 68 65 73 65 20 72 6f 75  sing.  These rou
fa90: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 72 75  tines return tru
faa0: 65 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  e if the input s
fab0: 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
fac0: 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
fad0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
fae0: 20 20 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73    A statement is
faf0: 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a   judged to be.**
fb00: 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
fb10: 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69  ends with a semi
fb20: 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20  colon token and 
fb30: 69 73 20 6e 6f 74 20 61 20 66 72 61 67 6d 65 6e  is not a fragmen
fb40: 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45 41 54 45  t of a.** CREATE
fb50: 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
fb60: 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20  nt.  Semicolons 
fb70: 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65  that are embedde
fb80: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69  d within.** stri
fb90: 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71  ng literals or q
fba0: 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72  uoted identifier
fbb0: 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e   names or commen
fbc0: 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e  ts are not.** in
fbd0: 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73  dependent tokens
fbe0: 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20   (they are part 
fbf0: 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20  of the token in 
fc00: 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a  which they are.*
fc10: 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20  * embedded) and 
fc20: 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  thus do not coun
fc30: 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74  t as a statement
fc40: 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a   terminator..**.
fc50: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
fc60: 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
fc70: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
fc80: 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
fc90: 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
fca0: 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
fcb0: 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  t SQL..**.** INV
fcc0: 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
fcd0: 48 31 30 35 31 31 7d 20 41 20 73 75 63 63 65 73  H10511} A succes
fce0: 73 66 75 6c 20 65 76 61 6c 75 61 74 69 6f 6e 20  sful evaluation 
fcf0: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  of [sqlite3_comp
fd00: 6c 65 74 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20  lete()] or.**   
fd10: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
fd20: 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 66 75  complete16()] fu
fd30: 6e 63 74 69 6f 6e 73 20 73 68 61 6c 6c 0a 2a 2a  nctions shall.**
fd40: 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
fd50: 20 61 20 6e 75 6d 65 72 69 63 20 31 20 69 66 20   a numeric 1 if 
fd60: 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
fd70: 6c 61 73 74 20 6e 6f 6e 2d 77 68 69 74 65 73 70  last non-whitesp
fd80: 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ace.**          
fd90: 74 6f 6b 65 6e 20 69 6e 20 74 68 65 69 72 20 69  token in their i
fda0: 6e 70 75 74 20 69 73 20 61 20 73 65 6d 69 63 6f  nput is a semico
fdb0: 6c 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20  lon that is not 
fdc0: 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 20 20  in between.**   
fdd0: 20 20 20 20 20 20 20 74 68 65 20 42 45 47 49 4e         the BEGIN
fde0: 20 61 6e 64 20 45 4e 44 20 6f 66 20 61 20 43 52   and END of a CR
fdf0: 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61  EATE TRIGGER sta
fe00: 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tement..**.** {H
fe10: 31 30 35 31 32 7d 20 49 66 20 61 20 6d 65 6d 6f  10512} If a memo
fe20: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
fe30: 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
fe40: 67 20 61 6e 20 69 6e 76 6f 63 61 74 69 6f 6e 0a  g an invocation.
fe50: 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 5b  **          of [
fe60: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
fe70: 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
fe80: 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 74 68  complete16()] th
fe90: 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  en the.**       
fea0: 20 20 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c     routine shall
feb0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
fec0: 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53  NOMEM]..**.** AS
fed0: 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
fee0: 20 7b 41 31 30 35 31 32 7d 20 54 68 65 20 69 6e   {A10512} The in
fef0: 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
ff00: 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
ff10: 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
ff20: 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
ff30: 20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a    UTF-8 string..
ff40: 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 33 7d 20 54  **.** {A10513} T
ff50: 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
ff60: 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
ff70: 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
ff80: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
ff90: 20 20 20 20 20 20 20 20 20 55 54 46 2d 31 36 20           UTF-16 
ffa0: 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
ffb0: 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
ffc0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
ffd0: 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
ffe0: 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
fff0: 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
10000 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
10010 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10020 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
10030 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
10040 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
10050 73 20 7b 48 31 32 33 31 30 7d 20 3c 53 34 30 34  s {H12310} <S404
10060 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  00>.**.** This r
10070 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
10080 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
10090 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
100a0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a  voked whenever.*
100b0 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
100c0 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64  made to open a d
100d0 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68  atabase table th
100e0 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  at another threa
100f0 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
10100 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a  has locked..**.*
10110 2a 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61  * If the busy ca
10120 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
10130 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
10140 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
10150 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
10160 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
10170 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
10180 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
10190 63 6b 2e 20 49 66 20 74 68 65 20 62 75 73 79 20  ck. If the busy 
101a0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
101b0 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
101c0 65 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20  e callback will 
101d0 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
101e0 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
101f0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
10200 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68  rgument to the h
10210 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79  andler is a copy
10220 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f   of the void* po
10230 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  inter which.** i
10240 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
10250 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
10260 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20  busy_handler(). 
10270 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
10280 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68  ment to.** the h
10290 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
102a0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
102b0 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
102c0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
102d0 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
102e0 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e   for this lockin
102f0 67 20 65 76 65 6e 74 2e 20 20 49 66 20 74 68 65  g event.  If the
10300 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
10310 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
10320 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
10330 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
10340 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
10350 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
10360 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
10370 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
10380 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72  LOCKED] is retur
10390 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ned..** If the c
103a0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
103b0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
103c0 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
103d0 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  * is made to ope
103e0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
103f0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74  or reading and t
10400 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
10410 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
10420 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
10430 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
10440 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
10450 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
10460 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
10470 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
10480 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 64 65  on. If SQLite de
10490 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
104a0 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
104b0 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
104c0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
104d0 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
104e0 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
104f0 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
10500 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
10510 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
10520 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
10530 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
10540 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
10550 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
10560 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
10570 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
10580 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
10590 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
105a0 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
105b0 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
105c0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
105d0 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
105e0 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
105f0 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
10600 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
10610 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
10620 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
10630 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
10640 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
10650 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
10660 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
10670 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
10680 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
10690 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
106a0 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
106b0 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
106c0 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
106d0 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
106e0 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
106f0 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
10700 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
10710 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
10720 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
10730 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
10740 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
10750 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
10760 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
10770 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
10780 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
10790 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
107a0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
107b0 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
107c0 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  **.** The defaul
107d0 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
107e0 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  is NULL..**.** T
107f0 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  he [SQLITE_BUSY]
10800 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72   error is conver
10810 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49  ted to [SQLITE_I
10820 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
10830 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
10840 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66  in the middle of
10850 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63   a large transac
10860 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74  tion where all t
10870 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69  he.** changes wi
10880 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20  ll not fit into 
10890 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61  the in-memory ca
108a0 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  che.  SQLite wil
108b0 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c  l.** already hol
108c0 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63  d a RESERVED loc
108d0 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  k on the databas
108e0 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e  e file, but it n
108f0 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  eeds.** to promo
10900 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20  te this lock to 
10910 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61  EXCLUSIVE so tha
10920 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63  t it can spill c
10930 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e  ache.** pages in
10940 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
10950 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72  file without har
10960 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a  m to concurrent.
10970 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 20  ** readers.  If 
10980 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
10990 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b  promote the lock
109a0 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65  , then the in-me
109b0 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69  mory.** cache wi
109c0 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e  ll be left in an
109d0 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74   inconsistent st
109e0 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65  ate and so the e
109f0 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20  rror.** code is 
10a00 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68  promoted from th
10a10 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e  e relatively ben
10a20 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  ign [SQLITE_BUSY
10a30 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ] to.** the more
10a40 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f   severe [SQLITE_
10a50 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20  IOERR_BLOCKED]. 
10a60 20 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65   This error code
10a70 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f   promotion.** fo
10a80 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69  rces an automati
10a90 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68  c rollback of th
10aa0 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20  e changes.  See 
10ab0 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
10ac0 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d  /cvstrac/wiki?p=
10ad0 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
10ae0 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a  ingBusyError">.*
10af0 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  * CorruptionFoll
10b00 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f  owingBusyError</
10b10 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72  a> wiki page for
10b20 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66   a discussion of
10b30 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20   why.** this is 
10b40 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a  important..**.**
10b50 20 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20   There can only 
10b60 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
10b70 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
10b80 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
10b90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10ba0 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
10bb0 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
10bc0 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
10bd0 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
10be0 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74  dler.  Note that
10bf0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
10c00 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
10c10 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73  ].** will also s
10c20 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20  et or clear the 
10c30 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
10c40 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
10c50 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 31 7d 20 54  **.** {H12311} T
10c60 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  he [sqlite3_busy
10c70 5f 68 61 6e 64 6c 65 72 28 44 2c 43 2c 41 29 5d  _handler(D,C,A)]
10c80 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
10c90 72 65 70 6c 61 63 65 0a 2a 2a 20 20 20 20 20 20  replace.**      
10ca0 20 20 20 20 62 75 73 79 20 63 61 6c 6c 62 61 63      busy callbac
10cb0 6b 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61  k in the [databa
10cc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
10cd0 20 77 69 74 68 20 61 20 6e 65 77 0a 2a 2a 20 20   with a new.**  
10ce0 20 20 20 20 20 20 20 20 61 20 6e 65 77 20 62 75          a new bu
10cf0 73 79 20 68 61 6e 64 6c 65 72 20 43 20 61 6e 64  sy handler C and
10d00 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
10d10 61 20 70 6f 69 6e 74 65 72 20 41 2e 0a 2a 2a 0a  a pointer A..**.
10d20 2a 2a 20 7b 48 31 32 33 31 32 7d 20 4e 65 77 6c  ** {H12312} Newl
10d30 79 20 63 72 65 61 74 65 64 20 5b 64 61 74 61 62  y created [datab
10d40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
10d50 20 73 68 61 6c 6c 20 68 61 76 65 20 61 20 62 75   shall have a bu
10d60 73 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68  sy.**          h
10d70 61 6e 64 6c 65 72 20 6f 66 20 4e 55 4c 4c 2e 0a  andler of NULL..
10d80 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 34 7d 20 57  **.** {H12314} W
10d90 68 65 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20  hen two or more 
10da0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10db0 74 69 6f 6e 73 5d 20 73 68 61 72 65 20 61 0a 2a  tions] share a.*
10dc0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
10dd0 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
10de0 64 5f 63 61 63 68 65 20 7c 20 63 6f 6d 6d 6f 6e  d_cache | common
10df0 20 63 61 63 68 65 5d 2c 0a 2a 2a 20 20 20 20 20   cache],.**     
10e00 20 20 20 20 20 74 68 65 20 62 75 73 79 20 68 61       the busy ha
10e10 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 64 61  ndler for the da
10e20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10e30 6e 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  n currently usin
10e40 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  g.**          th
10e50 65 20 63 61 63 68 65 20 73 68 61 6c 6c 20 62 65  e cache shall be
10e60 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
10e70 65 20 63 61 63 68 65 20 65 6e 63 6f 75 6e 74 65  e cache encounte
10e80 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a  rs a lock..**.**
10e90 20 7b 48 31 32 33 31 36 7d 20 49 66 20 61 20 62   {H12316} If a b
10ea0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
10eb0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 72  back returns zer
10ec0 6f 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 69  o, then the SQLi
10ed0 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  te interface.** 
10ee0 20 20 20 20 20 20 20 20 20 74 68 61 74 20 70 72           that pr
10ef0 6f 76 6f 6b 65 64 20 74 68 65 20 6c 6f 63 6b 69  ovoked the locki
10f00 6e 67 20 65 76 65 6e 74 20 73 68 61 6c 6c 20 72  ng event shall r
10f10 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
10f20 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  SY]..**.** {H123
10f30 31 38 7d 20 53 51 4c 69 74 65 20 73 68 61 6c 6c  18} SQLite shall
10f40 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 62 75 73   invokes the bus
10f50 79 20 68 61 6e 64 6c 65 72 20 77 69 74 68 20 74  y handler with t
10f60 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 77 68 69  wo arguments whi
10f70 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ch.**          a
10f80 72 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  re a copy of the
10f90 20 70 6f 69 6e 74 65 72 20 73 75 70 70 6c 69 65   pointer supplie
10fa0 64 20 62 79 20 74 68 65 20 33 72 64 20 70 61 72  d by the 3rd par
10fb0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20  ameter to.**    
10fc0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
10fd0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 61  usy_handler()] a
10fe0 6e 64 20 61 20 63 6f 75 6e 74 20 6f 66 20 74 68  nd a count of th
10ff0 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 72 69 6f  e number of prio
11000 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  r.**          in
11010 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
11020 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
11030 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69  r the same locki
11040 6e 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  ng event..**.** 
11050 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
11060 2a 2a 20 7b 41 31 32 33 31 39 7d 20 41 20 62 75  ** {A12319} A bu
11070 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
11080 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
11090 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
110a0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
110b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
110c0 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
110d0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
110e0 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
110f0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
11100 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
11110 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
11120 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
11130 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
11140 79 20 54 69 6d 65 6f 75 74 20 7b 48 31 32 33 34  y Timeout {H1234
11150 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a  0} <S40410>.**.*
11160 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73  * This routine s
11170 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
11180 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
11190 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
111a0 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
111b0 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
111c0 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
111d0 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
111e0 2e 20 20 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a  .  The handler.*
111f0 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  * will sleep mul
11200 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
11210 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  l at least "ms" 
11220 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
11230 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65  sleeping.** have
11240 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b 48   accumulated. {H
11250 31 32 33 34 33 7d 20 41 66 74 65 72 20 22 6d 73  12343} After "ms
11260 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
11270 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
11280 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
11290 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
112a0 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
112b0 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
112c0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
112d0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
112e0 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43  LOCKED]..**.** C
112f0 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
11300 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
11310 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
11320 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
11330 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
11340 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
11350 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20  **.** There can 
11360 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
11370 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f   busy handler fo
11380 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
11390 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
113a0 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20  ection] any any 
113b0 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
113c0 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
113d0 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
113e0 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
113f0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
11400 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
11410 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
11420 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
11430 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
11440 72 20 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a  r is cleared..**
11450 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
11460 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 31 7d 20 54  **.** {H12341} T
11470 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  he [sqlite3_busy
11480 5f 74 69 6d 65 6f 75 74 28 29 5d 20 66 75 6e 63  _timeout()] func
11490 74 69 6f 6e 20 73 68 61 6c 6c 20 6f 76 65 72 72  tion shall overr
114a0 69 64 65 20 61 6e 79 20 70 72 69 6f 72 0a 2a 2a  ide any prior.**
114b0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
114c0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
114d0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62  )] or [sqlite3_b
114e0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 73  usy_handler()] s
114f0 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  etting.**       
11500 20 20 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b     on the same [
11510 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11520 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ion]..**.** {H12
11530 33 34 33 7d 20 49 66 20 74 68 65 20 32 6e 64 20  343} If the 2nd 
11540 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
11550 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
11560 75 74 28 29 5d 20 69 73 20 6c 65 73 73 20 74 68  ut()] is less th
11570 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  an.**          o
11580 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2c  r equal to zero,
11590 20 74 68 65 6e 20 74 68 65 20 62 75 73 79 20 68   then the busy h
115a0 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20 62 65 20  andler shall be 
115b0 63 6c 65 61 72 65 64 20 73 6f 20 74 68 61 74 0a  cleared so that.
115c0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 20  **          all 
115d0 73 75 62 73 65 71 75 65 6e 74 20 6c 6f 63 6b 69  subsequent locki
115e0 6e 67 20 65 76 65 6e 74 73 20 69 6d 6d 65 64 69  ng events immedi
115f0 61 74 65 6c 79 20 72 65 74 75 72 6e 20 5b 53 51  ately return [SQ
11600 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
11610 2a 20 7b 48 31 32 33 34 34 7d 20 49 66 20 74 68  * {H12344} If th
11620 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
11630 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  to [sqlite3_busy
11640 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 61  _timeout()] is a
11650 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 20   positive.**    
11660 20 20 20 20 20 20 6e 75 6d 62 65 72 20 4e 2c 20        number N, 
11670 74 68 65 6e 20 61 20 62 75 73 79 20 68 61 6e 64  then a busy hand
11680 6c 65 72 20 73 68 61 6c 6c 20 62 65 20 73 65 74  ler shall be set
11690 20 74 68 61 74 20 72 65 70 65 61 74 65 64 6c 79   that repeatedly
116a0 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20   calls.**       
116b0 20 20 20 74 68 65 20 78 53 6c 65 65 70 28 29 20     the xSleep() 
116c0 6d 65 74 68 6f 64 20 69 6e 20 74 68 65 20 5b 73  method in the [s
116d0 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53  qlite3_vfs | VFS
116e0 20 69 6e 74 65 72 66 61 63 65 5d 20 75 6e 74 69   interface] unti
116f0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 69  l.**          ei
11700 74 68 65 72 20 74 68 65 20 6c 6f 63 6b 20 63 6c  ther the lock cl
11710 65 61 72 73 20 6f 72 20 75 6e 74 69 6c 20 74 68  ears or until th
11720 65 20 63 75 6d 75 6c 61 74 69 76 65 20 73 6c 65  e cumulative sle
11730 65 70 20 74 69 6d 65 0a 2a 2a 20 20 20 20 20 20  ep time.**      
11740 20 20 20 20 72 65 70 6f 72 74 65 64 20 62 61 63      reported bac
11750 6b 20 62 79 20 78 53 6c 65 65 70 28 29 20 65 78  k by xSleep() ex
11760 63 65 65 64 73 20 4e 20 6d 69 6c 6c 69 73 65 63  ceeds N millisec
11770 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  onds..*/.int sql
11780 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
11790 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
117a0 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
117b0 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
117c0 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
117d0 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 20 7b  unning Queries {
117e0 48 31 32 33 37 30 7d 20 3c 53 31 30 30 30 30 3e  H12370} <S10000>
117f0 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
11800 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
11810 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
11820 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
11830 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
11840 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
11850 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
11860 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
11870 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
11880 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
11890 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
118a0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
118b0 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
118c0 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
118d0 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
118e0 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
118f0 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
11900 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
11910 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
11920 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
11930 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
11940 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
11950 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
11960 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
11970 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
11980 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
11990 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
119a0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
119b0 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
119c0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
119d0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
119e0 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
119f0 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
11a00 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
11a10 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
11a20 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
11a30 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
11a40 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
11a50 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
11a60 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
11a70 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
11a80 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
11a90 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
11aa0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
11ab0 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
11ac0 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
11ad0 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
11ae0 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
11af0 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
11b00 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
11b10 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
11b20 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
11b30 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
11b40 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
11b50 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
11b60 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
11b70 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
11b80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11b90 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
11ba0 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
11bb0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
11bc0 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
11bd0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
11be0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
11bf0 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
11c00 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
11c10 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
11c20 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78  ..**.** As an ex
11c30 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73  ample of the res
11c40 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74  ult table format
11c50 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72  , suppose a quer
11c60 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61  y result.** is a
11c70 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
11c80 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
11c90 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d  e>.**        Nam
11ca0 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a  e        | Age.*
11cb0 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d  *        -------
11cc0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
11cd0 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65  .**        Alice
11ce0 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20         | 43.**  
11cf0 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20        Bob       
11d00 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20    | 28.**       
11d10 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32   Cindy       | 2
11d20 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  1.** </pre></blo
11d30 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
11d40 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c  here are two col
11d50 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74  umn (M==2) and t
11d60 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29  hree rows (N==3)
11d70 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72  .  Thus the.** r
11d80 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20  esult table has 
11d90 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70  8 entries.  Supp
11da0 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74  ose the result t
11db0 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a  able is stored.*
11dc0 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61  * in an array na
11dd0 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54  mes azResult.  T
11de0 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c  hen azResult hol
11df0 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a  ds this content:
11e00 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
11e10 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
11e20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
11e30 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20  0] = "Name";.** 
11e40 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
11e50 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  #91;1] = "Age";.
11e60 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
11e70 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69  lt&#91;2] = "Ali
11e80 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ce";.**        a
11e90 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d  zResult&#91;3] =
11ea0 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "43";.**       
11eb0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d   azResult&#91;4]
11ec0 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20   = "Bob";.**    
11ed0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
11ee0 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  ;5] = "28";.**  
11ef0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
11f00 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b  91;6] = "Cindy";
11f10 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
11f20 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31  ult&#91;7] = "21
11f30 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
11f40 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
11f50 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
11f60 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
11f70 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
11f80 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
11f90 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
11fa0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
11fb0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
11fc0 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
11fd0 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
11fe0 61 72 61 6d 65 74 65 72 2e 20 20 49 74 20 72 65  arameter.  It re
11ff0 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
12000 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
12010 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
12020 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
12030 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
12040 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
12050 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
12060 20 75 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c   using the resul
12070 74 2c 20 69 74 20 73 68 6f 75 6c 64 0a 2a 2a 20  t, it should.** 
12080 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
12090 20 74 6f 20 74 68 65 20 72 65 73 75 6c 74 20 74   to the result t
120a0 61 62 6c 65 20 74 6f 20 73 71 6c 69 74 65 33 5f  able to sqlite3_
120b0 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
120c0 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
120d0 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
120e0 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
120f0 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
12100 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
12110 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
12120 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
12130 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
12140 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
12150 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
12160 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
12170 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
12180 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
12190 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
121a0 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
121b0 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
121c0 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
121d0 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
121e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
121f0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
12200 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
12210 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
12220 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
12230 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
12240 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
12250 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
12260 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
12270 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
12280 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
12290 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
122a0 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
122b0 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
122c0 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
122d0 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
122e0 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
122f0 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
12300 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
12310 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
12320 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
12330 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
12340 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
12350 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
12360 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
12370 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
12380 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
12390 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  rmsg()]..**.** I
123a0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
123b0 20 7b 48 31 32 33 37 31 7d 20 49 66 20 61 20 5b   {H12371} If a [
123c0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
123d0 65 28 29 5d 20 66 61 69 6c 73 20 61 20 6d 65 6d  e()] fails a mem
123e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ory allocation, 
123f0 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
12400 20 69 74 20 73 68 61 6c 6c 20 66 72 65 65 20 74   it shall free t
12410 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
12420 75 6e 64 65 72 20 63 6f 6e 73 74 72 75 63 74 69  under constructi
12430 6f 6e 2c 20 61 62 6f 72 74 20 74 68 65 0a 2a 2a  on, abort the.**
12440 20 20 20 20 20 20 20 20 20 20 71 75 65 72 79 20            query 
12450 69 6e 20 70 72 6f 63 65 73 73 2c 20 73 6b 69 70  in process, skip
12460 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
12470 71 75 65 72 69 65 73 2c 20 73 65 74 20 74 68 65  queries, set the
12480 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a 70 61  .**          *pa
12490 7a 52 65 73 75 6c 74 20 6f 75 74 70 75 74 20 70  zResult output p
124a0 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 61  ointer to NULL a
124b0 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
124c0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
124d0 7b 48 31 32 33 37 33 7d 20 49 66 20 74 68 65 20  {H12373} If the 
124e0 70 6e 43 6f 6c 75 6d 6e 20 70 61 72 61 6d 65 74  pnColumn paramet
124f0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67  er to [sqlite3_g
12500 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e  et_table()] is n
12510 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20  ot NULL.**      
12520 20 20 20 20 74 68 65 6e 20 61 20 73 75 63 63 65      then a succe
12530 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
12540 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   of [sqlite3_get
12550 5f 74 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a  _table()] shall.
12560 2a 2a 20 20 20 20 20 20 20 20 20 20 77 72 69 74  **          writ
12570 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
12580 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a  columns in the.*
12590 2a 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c  *          resul
125a0 74 20 73 65 74 20 6f 66 20 74 68 65 20 71 75 65  t set of the que
125b0 72 79 20 69 6e 74 6f 20 2a 70 6e 43 6f 6c 75 6d  ry into *pnColum
125c0 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 34  n..**.** {H12374
125d0 7d 20 49 66 20 74 68 65 20 70 6e 52 6f 77 20 70  } If the pnRow p
125e0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
125f0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
12600 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a  ] is not NULL.**
12610 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 61            then a
12620 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
12630 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
12640 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
12650 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20  shall.**        
12660 20 20 77 72 69 74 65 73 20 74 68 65 20 6e 75 6d    writes the num
12670 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 20 74  ber of rows in t
12680 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
12690 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65  esult set of the
126a0 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 70 6e 52   query into *pnR
126b0 6f 77 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37  ow..**.** {H1237
126c0 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  6} A successful 
126d0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
126e0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
126f0 28 29 5d 20 74 68 61 74 20 63 6f 6d 70 75 74 65  ()] that compute
12700 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 20  s.**          N 
12710 72 6f 77 73 20 6f 66 20 72 65 73 75 6c 74 20 77  rows of result w
12720 69 74 68 20 43 20 63 6f 6c 75 6d 6e 73 20 70 65  ith C columns pe
12730 72 20 72 6f 77 20 73 68 61 6c 6c 20 6d 61 6b 65  r row shall make
12740 20 2a 70 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 20   *pazResult.**  
12750 20 20 20 20 20 20 20 20 70 6f 69 6e 74 20 74 6f          point to
12760 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
12770 6e 74 65 72 73 20 74 6f 20 28 4e 2b 31 29 2a 43  nters to (N+1)*C
12780 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 74   strings where t
12790 68 65 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20  he first.**     
127a0 20 20 20 20 20 43 20 73 74 72 69 6e 67 73 20 61       C strings a
127b0 72 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20  re column names 
127c0 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  as obtained from
127d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
127e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
127f0 65 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73  e()] and the res
12800 74 20 61 72 65 20 63 6f 6c 75 6d 6e 20 72 65 73  t are column res
12810 75 6c 74 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20  ult values.**   
12820 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20         obtained 
12830 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
12840 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
12850 0a 2a 2a 20 7b 48 31 32 33 37 39 7d 20 54 68 65  .** {H12379} The
12860 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20 70   values in the p
12870 61 7a 52 65 73 75 6c 74 20 61 72 72 61 79 20 72  azResult array r
12880 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
12890 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
128a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61  .**          sha
128b0 6c 6c 20 72 65 6d 61 69 6e 20 76 61 6c 69 64 20  ll remain valid 
128c0 75 6e 74 69 6c 20 63 6c 65 61 72 65 64 20 62 79  until cleared by
128d0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
128e0 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  able()]..**.** {
128f0 48 31 32 33 38 32 7d 20 57 68 65 6e 20 61 6e 20  H12382} When an 
12900 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
12910 69 6e 67 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ing evaluation o
12920 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  f [sqlite3_get_t
12930 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20  able()].**      
12940 20 20 20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e      the function
12950 20 73 68 61 6c 6c 20 73 65 74 20 2a 70 61 7a 52   shall set *pazR
12960 65 73 75 6c 74 20 74 6f 20 4e 55 4c 4c 2c 20 77  esult to NULL, w
12970 72 69 74 65 20 61 6e 20 65 72 72 6f 72 20 6d 65  rite an error me
12980 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  ssage.**        
12990 20 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62    into memory ob
129a0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
129b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
129c0 6d 61 6b 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  make.**         
129d0 20 2a 2a 70 7a 45 72 72 6d 73 67 20 70 6f 69 6e   **pzErrmsg poin
129e0 74 20 74 6f 20 74 68 61 74 20 65 72 72 6f 72 20  t to that error 
129f0 6d 65 73 73 61 67 65 2c 20 61 6e 64 20 72 65 74  message, and ret
12a00 75 72 6e 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  urn a.**        
12a10 20 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65    appropriate [e
12a20 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69  rror code]..*/.i
12a30 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
12a40 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
12a50 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
12a60 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
12a70 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
12a80 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
12a90 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
12aa0 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
12ab0 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
12ac0 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
12ad0 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
12ae0 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
12af0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
12b00 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
12b10 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
12b20 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
12b30 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
12b40 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
12b50 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
12b60 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
12b70 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
12b80 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
12b90 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
12ba0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
12bb0 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
12bc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12bd0 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
12be0 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
12bf0 6f 6e 73 20 7b 48 31 37 34 30 30 7d 20 3c 53 37  ons {H17400} <S7
12c00 30 30 30 30 3e 3c 53 32 30 30 30 30 3e 0a 2a 2a  0000><S20000>.**
12c10 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
12c20 65 73 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65  es are workalike
12c30 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
12c40 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
12c50 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
12c60 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
12c70 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  ibrary..**.** Th
12c80 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
12c90 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
12ca0 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
12cb0 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
12cc0 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
12cd0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
12ce0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
12cf0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
12d00 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
12d10 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
12d20 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
12d30 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
12d40 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
12d50 2e 20 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73  .  Both routines
12d60 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
12d70 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
12d80 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
12d90 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
12da0 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
12db0 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
12dc0 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
12dd0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71  ing..**.** In sq
12de0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
12df0 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
12e00 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
12e10 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
12e20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
12e30 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
12e40 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
12e50 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
12e60 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
12e70 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
12e80 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
12e90 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
12ea0 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
12eb0 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
12ec0 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
12ed0 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
12ee0 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
12ef0 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54  m snprintf().  T
12f00 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
12f10 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
12f20 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
12f30 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
12f40 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
12f50 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
12f60 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68  y.  Note also th
12f70 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
12f80 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
12f90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
12fa0 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
12fb0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
12fc0 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
12fd0 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
12fe0 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
12ff0 2e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  .  We admit that
13000 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
13010 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
13020 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
13030 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
13040 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
13050 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
13060 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
13070 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
13080 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
13090 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
130a0 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
130b0 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61  .**.** As long a
130c0 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
130d0 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
130e0 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
130f0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
13100 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
13110 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
13120 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
13130 65 64 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ed.  The first.*
13140 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
13150 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
13160 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
13170 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
13180 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
13190 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
131a0 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
131b0 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
131c0 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
131d0 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
131e0 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
131f0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
13200 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
13210 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
13220 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
13230 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
13240 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
13250 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
13260 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
13270 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
13280 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
13290 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
132a0 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
132b0 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
132c0 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a  ", "%Q", and "%z
132d0 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
132e0 20 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77   The %q option w
132f0 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
13300 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
13310 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69  tes a null-termi
13320 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
13330 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e  from the argumen
13340 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20  t list.  But %q 
13350 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65  also doubles eve
13360 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  ry '\'' characte
13370 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69  r..** %q is desi
13380 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73  gned for use ins
13390 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74  ide a string lit
133a0 65 72 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69  eral.  By doubli
133b0 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
133c0 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
133d0 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
133e0 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
133f0 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
13400 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
13410 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
13420 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74  xample, assume t
13430 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  he string variab
13440 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e  le zText contain
13450 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77  s text as follow
13460 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
13470 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
13480 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74  har *zText = "It
13490 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22  's a happy day!"
134a0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
134b0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f  ckquote>.**.** O
134c0 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
134d0 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
134e0 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
134f0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
13500 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
13510 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
13520 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
13530 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
13540 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20   VALUES('%q')", 
13550 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
13560 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
13570 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
13580 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
13590 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
135a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
135b0 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71  * Because the %q
135c0 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
135d0 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27  s used, the '\''
135e0 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54   character in zT
135f0 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65  ext.** is escape
13600 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65  d and the SQL ge
13610 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f  nerated is as fo
13620 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
13630 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
13640 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
13650 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
13660 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  ''s a happy day!
13670 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ').** </pre></bl
13680 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
13690 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e  This is correct.
136a0 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73    Had we used %s
136b0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20   instead of %q, 
136c0 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51  the generated SQ
136d0 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20  L.** would have 
136e0 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73  looked like this
136f0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
13700 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
13710 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
13720 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20   VALUES('It's a 
13730 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a  happy day!');.**
13740 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
13750 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
13760 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69  second example i
13770 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20  s an SQL syntax 
13780 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e  error.  As a gen
13790 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68  eral rule you sh
137a0 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75  ould.** always u
137b0 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66  se %q instead of
137c0 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69   %s when inserti
137d0 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73  ng text into a s
137e0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a  tring literal..*
137f0 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69  *.** The %Q opti
13800 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
13810 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
13820 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
13830 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
13840 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
13850 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
13860 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
13870 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
13880 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
13890 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
138a0 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
138b0 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
138c0 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
138d0 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
138e0 73 29 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  s) in place of t
138f0 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53  he %Q option.  S
13900 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  o, for example, 
13910 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a  one could say:.*
13920 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
13930 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
13940 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
13950 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
13960 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
13970 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a  S(%Q)", zText);.
13980 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
13990 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
139a0 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
139b0 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
139c0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
139d0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  te>.**.** The co
139e0 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65  de above will re
139f0 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53  nder a correct S
13a00 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
13a10 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69  the zSQL.** vari
13a20 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65  able even if the
13a30 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20   zText variable 
13a40 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
13a50 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a  r..**.** The "%z
13a60 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
13a70 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c  ion works exactl
13a80 79 20 6c 69 6b 65 20 22 25 73 22 20 77 69 74 68  y like "%s" with
13a90 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
13aa0 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
13ab0 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
13ac0 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
13ad0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
13ae0 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
13af0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
13b00 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
13b10 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  ng. {END}.**.** 
13b20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
13b30 2a 20 7b 48 31 37 34 30 33 7d 20 20 54 68 65 20  * {H17403}  The 
13b40 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
13b50 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
13b60 5f 76 6d 70 72 69 6e 74 66 28 29 5d 20 69 6e 74  _vmprintf()] int
13b70 65 72 66 61 63 65 73 0a 2a 2a 20 20 20 20 20 20  erfaces.**      
13b80 20 20 20 20 20 72 65 74 75 72 6e 20 65 69 74 68       return eith
13b90 65 72 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  er pointers to z
13ba0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
13bb0 54 46 2d 38 20 73 74 72 69 6e 67 73 20 68 65 6c  TF-8 strings hel
13bc0 64 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  d in.**         
13bd0 20 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65    memory obtaine
13be0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
13bf0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 4e 55 4c  malloc()] or NUL
13c00 4c 20 70 6f 69 6e 74 65 72 73 20 69 66 0a 2a 2a  L pointers if.**
13c10 20 20 20 20 20 20 20 20 20 20 20 61 20 63 61 6c             a cal
13c20 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  l to [sqlite3_ma
13c30 6c 6c 6f 63 28 29 5d 20 66 61 69 6c 73 2e 0a 2a  lloc()] fails..*
13c40 2a 0a 2a 2a 20 7b 48 31 37 34 30 36 7d 20 20 54  *.** {H17406}  T
13c50 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  he [sqlite3_snpr
13c60 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63  intf()] interfac
13c70 65 20 77 72 69 74 65 73 20 61 20 7a 65 72 6f 2d  e writes a zero-
13c80 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20  terminated.**   
13c90 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74          UTF-8 st
13ca0 72 69 6e 67 20 69 6e 74 6f 20 74 68 65 20 62 75  ring into the bu
13cb0 66 66 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20  ffer pointed to 
13cc0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
13cd0 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20  rameter.**      
13ce0 20 20 20 20 20 70 72 6f 76 69 64 65 64 20 74 68       provided th
13cf0 61 74 20 74 68 65 20 66 69 72 73 74 20 70 61 72  at the first par
13d00 61 6d 65 74 65 72 20 69 73 20 67 72 65 61 74 65  ameter is greate
13d10 72 20 74 68 61 6e 20 7a 65 72 6f 2e 0a 2a 2a 0a  r than zero..**.
13d20 2a 2a 20 7b 48 31 37 34 30 37 7d 20 20 54 68 65  ** {H17407}  The
13d30 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
13d40 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  tf()] interface 
13d50 64 6f 65 73 20 6e 6f 74 20 77 72 69 74 65 20 73  does not write s
13d60 6c 6f 74 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20  lots of.**      
13d70 20 20 20 20 20 69 74 73 20 6f 75 74 70 75 74 20       its output 
13d80 62 75 66 66 65 72 20 28 74 68 65 20 73 65 63 6f  buffer (the seco
13d90 6e 64 20 70 61 72 61 6d 65 74 65 72 29 20 6f 75  nd parameter) ou
13da0 74 73 69 64 65 20 74 68 65 20 72 61 6e 67 65 0a  tside the range.
13db0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 66 20  **           of 
13dc0 30 20 74 68 72 6f 75 67 68 20 4e 2d 31 20 28 77  0 through N-1 (w
13dd0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 66 69  here N is the fi
13de0 72 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  rst parameter).*
13df0 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 67 61  *           rega
13e00 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6c 65  rdless of the le
13e10 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
13e20 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ng.**           
13e30 72 65 71 75 65 73 74 65 64 20 62 79 20 74 68 65  requested by the
13e40 20 66 6f 72 6d 61 74 20 73 70 65 63 69 66 69 63   format specific
13e50 61 74 69 6f 6e 2e 0a 2a 2f 0a 63 68 61 72 20 2a  ation..*/.char *
13e60 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
13e70 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
13e80 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
13e90 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
13ea0 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
13eb0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
13ec0 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
13ed0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
13ee0 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
13ef0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
13f00 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d  cation Subsystem
13f10 20 7b 48 31 37 33 30 30 7d 20 3c 53 32 30 30 30   {H17300} <S2000
13f20 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  0>.**.** The SQL
13f30 69 74 65 20 63 6f 72 65 20 20 75 73 65 73 20 74  ite core  uses t
13f40 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
13f50 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
13f60 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
13f70 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
13f80 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
13f90 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
13fa0 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
13fb0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
13fc0 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
13fd0 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
13fe0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
13ff0 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
14000 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
14010 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
14020 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
14030 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
14040 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
14050 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
14060 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
14070 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
14080 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
14090 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
140a0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
140b0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20  arameter..** If 
140c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
140d0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
140e0 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
140f0 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
14100 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
14110 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 74  L pointer.  If t
14120 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74  he parameter N t
14130 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  o.** sqlite3_mal
14140 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
14150 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73   negative then s
14160 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
14170 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c  returns.** a NUL
14180 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
14190 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   Calling sqlite3
141a0 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
141b0 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
141c0 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
141d0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
141e0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
141f0 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
14200 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
14210 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
14220 62 65 20 72 65 75 73 65 64 2e 20 20 54 68 65 20  be reused.  The 
14230 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72  sqlite3_free() r
14240 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e  outine is.** a n
14250 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65  o-op if is calle
14260 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
14270 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20  inter.  Passing 
14280 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
14290 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  * to sqlite3_fre
142a0 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  e() is harmless.
142b0 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72    After being fr
142c0 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73  eed, memory.** s
142d0 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65  hould neither be
142e0 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65   read nor writte
142f0 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67  n.  Even reading
14300 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65   previously free
14310 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68  d.** memory migh
14320 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65  t result in a se
14330 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
14340 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
14350 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72   error..** Memor
14360 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20  y corruption, a 
14370 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
14380 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76  lt, or other sev
14390 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67  ere error.** mig
143a0 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c  ht result if sql
143b0 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63  ite3_free() is c
143c0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e  alled with a non
143d0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68  -NULL pointer th
143e0 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62  at.** was not ob
143f0 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
14400 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
14410 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 2e 0a  sqlite3_free()..
14420 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
14430 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65  3_realloc() inte
14440 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
14450 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
14460 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
14470 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c  ation to be at l
14480 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68  east N bytes, wh
14490 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
144a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
144b0 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c  .  The memory al
144c0 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72  location to be r
144d0 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69  esized is the fi
144e0 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
144f0 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20  .  If the first 
14500 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
14510 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
14520 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
14530 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
14540 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
14550 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
14560 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
14570 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  N) where N is th
14580 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
14590 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
145a0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20 74  alloc()..** If t
145b0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
145c0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
145d0 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  ealloc() is zero
145e0 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
145f0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
14600 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
14610 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
14620 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
14630 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74  (P) where P is t
14640 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
14650 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
14660 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c 69  alloc()..** sqli
14670 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
14680 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
14690 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  to a memory allo
146a0 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20  cation.** of at 
146b0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
146c0 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66   size or NULL if
146d0 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f   sufficient memo
146e0 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  ry is unavailabl
146f0 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74 68  e..** If M is th
14700 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
14710 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
14720 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
14730 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
14740 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
14750 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
14760 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
14770 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
14780 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
14790 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20  alloc() and the 
147a0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
147b0 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66   is freed..** If
147c0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
147d0 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c  () returns NULL,
147e0 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20   then the prior 
147f0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73  allocation.** is
14800 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
14810 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74  * The memory ret
14820 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
14830 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71  _malloc() and sq
14840 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
14850 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
14860 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
14870 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
14880 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ary. {END}.**.**
14890 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d 70   The default imp
148a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
148b0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
148c0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 75  tion subsystem u
148d0 73 65 73 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f  ses.** the mallo
148e0 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61  c(), realloc() a
148f0 6e 64 20 66 72 65 65 28 29 20 70 72 6f 76 69 64  nd free() provid
14900 65 64 20 62 79 20 74 68 65 20 73 74 61 6e 64 61  ed by the standa
14910 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
14920 20 7b 48 31 37 33 38 32 7d 20 48 6f 77 65 76 65   {H17382} Howeve
14930 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
14940 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
14950 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 45 4d 4f  e.** SQLITE_MEMO
14960 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f  RY_SIZE=<i>NNN</
14970 69 3e 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  i> C preprocesso
14980 72 20 6d 61 63 72 6f 20 28 77 68 65 72 65 20 3c  r macro (where <
14990 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20  i>NNN</i>.** is 
149a0 61 6e 20 69 6e 74 65 67 65 72 29 2c 20 74 68 65  an integer), the
149b0 6e 20 53 51 4c 69 74 65 20 63 72 65 61 74 65 20  n SQLite create 
149c0 61 20 73 74 61 74 69 63 20 61 72 72 61 79 20 6f  a static array o
149d0 66 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 3c 69  f at least.** <i
149e0 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20 69  >NNN</i> bytes i
149f0 6e 20 73 69 7a 65 20 61 6e 64 20 75 73 65 73 20  n size and uses 
14a00 74 68 61 74 20 61 72 72 61 79 20 66 6f 72 20 61  that array for a
14a10 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
14a20 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  c.** memory allo
14a30 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b 45  cation needs. {E
14a40 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  ND}  Additional 
14a50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
14a60 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20   options.** may 
14a70 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
14a80 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a  re releases..**.
14a90 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
14aa0 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
14ab0 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
14ac0 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
14ad0 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
14ae0 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
14af0 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
14b00 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
14b10 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
14b20 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
14b30 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
14b40 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
14b50 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
14b60 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
14b70 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
14b80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
14b90 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
14ba0 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77  **.** The Window
14bb0 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
14bc0 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68  ayer calls.** th
14bd0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
14be0 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
14bf0 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
14c00 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
14c10 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
14c20 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
14c30 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
14c40 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
14c50 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
14c60 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
14c70 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
14c80 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
14c90 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
14ca0 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20  tion errors are 
14cb0 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
14cc0 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74   they are report
14cd0 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
14ce0 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
14cf0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
14d00 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
14d10 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
14d20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
14d30 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 33 7d 20 20  **.** {H17303}  
14d40 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  The [sqlite3_mal
14d50 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63  loc(N)] interfac
14d60 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
14d70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
14d80 20 20 20 20 20 20 20 20 20 20 20 61 20 6e 65 77             a new
14d90 6c 79 20 63 68 65 63 6b 65 64 2d 6f 75 74 20 62  ly checked-out b
14da0 6c 6f 63 6b 20 6f 66 20 61 74 20 6c 65 61 73 74  lock of at least
14db0 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f   N bytes of memo
14dc0 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ry.**           
14dd0 74 68 61 74 20 69 73 20 38 2d 62 79 74 65 20 61  that is 8-byte a
14de0 6c 69 67 6e 65 64 2c 20 6f 72 20 69 74 20 72 65  ligned, or it re
14df0 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 74  turns NULL if it
14e00 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20 20 20   is unable.**   
14e10 20 20 20 20 20 20 20 20 74 6f 20 66 75 6c 66 69          to fulfi
14e20 6c 6c 20 74 68 65 20 72 65 71 75 65 73 74 2e 0a  ll the request..
14e30 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 34 7d 20 20  **.** {H17304}  
14e40 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  The [sqlite3_mal
14e50 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61 63  loc(N)] interfac
14e60 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
14e70 20 70 6f 69 6e 74 65 72 20 69 66 0a 2a 2a 20 20   pointer if.**  
14e80 20 20 20 20 20 20 20 20 20 4e 20 69 73 20 6c 65           N is le
14e90 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
14ea0 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20   to zero..**.** 
14eb0 7b 48 31 37 33 30 35 7d 20 20 54 68 65 20 5b 73  {H17305}  The [s
14ec0 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d 20  qlite3_free(P)] 
14ed0 69 6e 74 65 72 66 61 63 65 20 72 65 6c 65 61 73  interface releas
14ee0 65 73 20 6d 65 6d 6f 72 79 20 70 72 65 76 69 6f  es memory previo
14ef0 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  usly.**         
14f00 20 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20    returned from 
14f10 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14f20 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
14f30 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20  ealloc()],.**   
14f40 20 20 20 20 20 20 20 20 6d 61 6b 69 6e 67 20 69          making i
14f50 74 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72 20  t available for 
14f60 72 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  reuse..**.** {H1
14f70 37 33 30 36 7d 20 20 41 20 63 61 6c 6c 20 74 6f  7306}  A call to
14f80 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 4e   [sqlite3_free(N
14f90 55 4c 4c 29 5d 20 69 73 20 61 20 68 61 72 6d 6c  ULL)] is a harml
14fa0 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a  ess no-op..**.**
14fb0 20 7b 48 31 37 33 31 30 7d 20 20 41 20 63 61 6c   {H17310}  A cal
14fc0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
14fd0 61 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69 73 20 65  alloc(0,N)] is e
14fe0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63  quivalent to a c
14ff0 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
15000 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
15010 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  loc(N)]..**.** {
15020 48 31 37 33 31 32 7d 20 20 41 20 63 61 6c 6c 20  H17312}  A call 
15030 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  to [sqlite3_real
15040 6c 6f 63 28 50 2c 30 29 5d 20 69 73 20 65 71 75  loc(P,0)] is equ
15050 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c  ivalent to a cal
15060 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  l.**           t
15070 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
15080 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  P)]..**.** {H173
15090 31 35 7d 20 20 54 68 65 20 53 51 4c 69 74 65 20  15}  The SQLite 
150a0 63 6f 72 65 20 75 73 65 73 20 5b 73 71 6c 69 74  core uses [sqlit
150b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
150c0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
150d0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ],.**           
150e0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  and [sqlite3_fre
150f0 65 28 29 5d 20 66 6f 72 20 61 6c 6c 20 6f 66 20  e()] for all of 
15100 69 74 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  its memory alloc
15110 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20  ation and.**    
15120 20 20 20 20 20 20 20 64 65 61 6c 6c 6f 63 61 74         deallocat
15130 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ion needs..**.**
15140 20 7b 48 31 37 33 31 38 7d 20 20 54 68 65 20 5b   {H17318}  The [
15150 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
15160 50 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  P,N)] interface 
15170 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 20 61  returns either a
15180 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20   pointer.**     
15190 20 20 20 20 20 20 74 6f 20 61 20 62 6c 6f 63 6b        to a block
151a0 20 6f 66 20 63 68 65 63 6b 65 64 2d 6f 75 74 20   of checked-out 
151b0 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61  memory of at lea
151c0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
151d0 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ze.**           
151e0 74 68 61 74 20 69 73 20 38 2d 62 79 74 65 20 61  that is 8-byte a
151f0 6c 69 67 6e 65 64 2c 20 6f 72 20 61 20 4e 55 4c  ligned, or a NUL
15200 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
15210 20 7b 48 31 37 33 32 31 7d 20 20 57 68 65 6e 20   {H17321}  When 
15220 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
15230 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61  (P,N)] returns a
15240 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
15250 72 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20  r, it first.**  
15260 20 20 20 20 20 20 20 20 20 63 6f 70 69 65 73 20           copies 
15270 74 68 65 20 66 69 72 73 74 20 4b 20 62 79 74 65  the first K byte
15280 73 20 6f 66 20 63 6f 6e 74 65 6e 74 20 66 72 6f  s of content fro
15290 6d 20 50 20 69 6e 74 6f 20 74 68 65 20 6e 65 77  m P into the new
152a0 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ly.**           
152b0 61 6c 6c 6f 63 61 74 65 64 20 62 6c 6f 63 6b 2c  allocated block,
152c0 20 77 68 65 72 65 20 4b 20 69 73 20 74 68 65 20   where K is the 
152d0 6c 65 73 73 65 72 20 6f 66 20 4e 20 61 6e 64 20  lesser of N and 
152e0 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 20  the size of.**  
152f0 20 20 20 20 20 20 20 20 20 74 68 65 20 62 75 66           the buf
15300 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  fer P..**.** {H1
15310 37 33 32 32 7d 20 20 57 68 65 6e 20 5b 73 71 6c  7322}  When [sql
15320 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e  ite3_realloc(P,N
15330 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  )] returns a non
15340 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69  -NULL pointer, i
15350 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20  t first.**      
15360 20 20 20 20 20 72 65 6c 65 61 73 65 73 20 74 68       releases th
15370 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a  e buffer P..**.*
15380 2a 20 7b 48 31 37 33 32 33 7d 20 20 57 68 65 6e  * {H17323}  When
15390 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
153a0 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20  c(P,N)] returns 
153b0 4e 55 4c 4c 2c 20 74 68 65 20 62 75 66 66 65 72  NULL, the buffer
153c0 20 50 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20   P is.**        
153d0 20 20 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 20     not modified 
153e0 6f 72 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  or released..**.
153f0 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
15400 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 30 7d 20 20  **.** {A17350}  
15410 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
15420 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
15430 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
15440 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
15450 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d  ].**           m
15460 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55  ust be either NU
15470 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74  LL or else point
15480 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ers obtained fro
15490 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20  m a prior.**    
154a0 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f         invocatio
154b0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
154c0 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
154d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
154e0 68 61 74 20 68 61 76 65 0a 2a 2a 20 20 20 20 20  hat have.**     
154f0 20 20 20 20 20 20 6e 6f 74 20 79 65 74 20 62 65        not yet be
15500 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
15510 2a 2a 20 7b 41 31 37 33 35 31 7d 20 20 54 68 65  ** {A17351}  The
15520 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
15530 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
15540 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
15550 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 62  **           a b
15560 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61  lock of memory a
15570 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
15580 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a   released using.
15590 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71  **           [sq
155a0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
155b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
155c0 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  c()]..*/.void *s
155d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
155e0 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
155f0 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
15600 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
15610 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
15620 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15630 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
15640 6f 72 20 53 74 61 74 69 73 74 69 63 73 20 7b 48  or Statistics {H
15650 31 37 33 37 30 7d 20 3c 53 33 30 32 31 30 3e 0a  17370} <S30210>.
15660 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
15670 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
15680 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
15690 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
156a0 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
156b0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
156c0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
156d0 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
156e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
156f0 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
15700 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
15710 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
15720 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
15730 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
15740 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 31  S:.**.** {H17371
15750 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  } The [sqlite3_m
15760 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f  emory_used()] ro
15770 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
15780 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
15790 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  s.**          of
157a0 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c   memory currentl
157b0 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d  y outstanding (m
157c0 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20  alloced but not 
157d0 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48  freed)..**.** {H
157e0 31 37 33 37 33 7d 20 54 68 65 20 5b 73 71 6c 69  17373} The [sqli
157f0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
15800 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
15810 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
15820 6d 75 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  mum.**          
15830 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
15840 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
15850 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
15860 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20  water mark.**   
15870 20 20 20 20 20 20 20 77 61 73 20 6c 61 73 74 20         was last 
15880 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  reset..**.** {H1
15890 37 33 37 34 7d 20 54 68 65 20 76 61 6c 75 65 73  7374} The values
158a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
158b0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
158c0 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20  d()] and.**     
158d0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65       [sqlite3_me
158e0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
158f0 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
15900 65 72 68 65 61 64 0a 2a 2a 20 20 20 20 20 20 20  erhead.**       
15910 20 20 20 61 64 64 65 64 20 62 79 20 53 51 4c 69     added by SQLi
15920 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
15930 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
15940 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
15950 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75 74 20  **          but 
15960 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
15970 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
15980 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
15990 6c 69 62 72 61 72 79 0a 2a 2a 20 20 20 20 20 20  library.**      
159a0 20 20 20 20 72 6f 75 74 69 6e 65 73 20 74 68 61      routines tha
159b0 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  t [sqlite3_mallo
159c0 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a  c()] may call..*
159d0 2a 0a 2a 2a 20 7b 48 31 37 33 37 35 7d 20 54 68  *.** {H17375} Th
159e0 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
159f0 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
15a00 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
15a10 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20   value of.**    
15a20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d        [sqlite3_m
15a30 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66  emory_used()] if
15a40 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
15a50 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
15a60 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
15a70 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
15a80 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
15a90 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   The value retur
15aa0 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ned.**          
15ab0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
15ac0 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d  ry_highwater(1)]
15ad0 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74   is the high-wat
15ae0 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20  er mark.**      
15af0 20 20 20 20 70 72 69 6f 72 20 74 6f 20 74 68 65      prior to the
15b00 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
15b10 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
15b20 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
15b30 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
15b40 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
15b50 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
15b60 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
15b70 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
15b80 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
15b90 20 47 65 6e 65 72 61 74 6f 72 20 7b 48 31 37 33   Generator {H173
15ba0 39 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a  90} <S20000>.**.
15bb0 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
15bc0 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
15bd0 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
15be0 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
15bf0 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
15c00 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
15c10 20 52 4f 57 49 44 73 20 77 68 65 6e 20 69 6e 73   ROWIDs when ins
15c20 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
15c30 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
15c40 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
15c50 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
15c60 20 70 6f 73 73 69 62 6c 65 20 52 4f 57 49 44 2e   possible ROWID.
15c70 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
15c80 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
15c90 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
15ca0 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
15cb0 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
15cc0 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
15cd0 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
15ce0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
15cf0 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
15d00 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
15d10 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  rposes..**.** A 
15d20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
15d30 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79  tine stores N by
15d40 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
15d50 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
15d60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
15d70 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69   time this routi
15d80 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65  ne is invoked (e
15d90 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79  ither internally
15da0 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70   or by.** the ap
15db0 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50  plication) the P
15dc0 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73  RNG is seeded us
15dd0 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
15de0 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
15df0 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
15e00 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
15e10 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
15e20 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f  fs] object..** O
15e30 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  n all subsequent
15e40 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68   invocations, th
15e50 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
15e60 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
15e70 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
15e80 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
15e90 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
15ea0 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
15eb0 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
15ec0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
15ed0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 39 32 7d  :.**.** {H17392}
15ee0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 61   The [sqlite3_ra
15ef0 6e 64 6f 6d 6e 65 73 73 28 4e 2c 50 29 5d 20 69  ndomness(N,P)] i
15f00 6e 74 65 72 66 61 63 65 20 77 72 69 74 65 73 20  nterface writes 
15f10 4e 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20  N bytes of.**   
15f20 20 20 20 20 20 20 20 68 69 67 68 2d 71 75 61 6c         high-qual
15f30 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
15f40 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
15f50 72 20 50 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  r P..*/.void sql
15f60 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
15f70 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
15f80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15f90 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
15fa0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
15fb0 6c 62 61 63 6b 73 20 7b 48 31 32 35 30 30 7d 20  lbacks {H12500} 
15fc0 3c 53 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S70100>.**.** T
15fd0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
15fe0 73 74 65 72 73 20 61 20 61 75 74 68 6f 72 69 7a  sters a authoriz
15ff0 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
16000 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
16010 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
16020 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
16030 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
16040 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61  gument..** The a
16050 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
16060 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
16070 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
16080 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
16090 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
160a0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
160b0 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
160c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
160d0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
160e0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e  _prepare16()] an
160f0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
16100 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 41 74 20  re16_v2()].  At 
16110 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
16120 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
16130 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
16140 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
16150 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
16160 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
16170 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
16180 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
16190 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
161a0 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
161b0 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
161c0 6f 77 65 64 2e 20 20 54 68 65 20 61 75 74 68 6f  owed.  The autho
161d0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
161e0 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
161f0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
16200 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
16210 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
16220 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
16230 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
16240 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
16250 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
16260 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
16270 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
16280 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
16290 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
162a0 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
162b0 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
162c0 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
162d0 72 2e 20 20 49 66 20 74 68 65 20 61 75 74 68 6f  r.  If the autho
162e0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
162f0 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
16300 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
16310 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
16320 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
16330 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
16340 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
16350 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
16360 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
16370 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
16380 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
16390 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
163a0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
163b0 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
163c0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
163d0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
163e0 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
163f0 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
16400 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
16410 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
16420 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
16430 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
16440 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
16450 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
16460 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
16470 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a  triggered the.**
16480 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
16490 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
164a0 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c  ror message expl
164b0 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61  aining that.** a
164c0 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
164d0 20 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69    If the authori
164e0 7a 65 72 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  zer code is [SQL
164f0 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
16500 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
16510 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
16520 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
16530 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
16540 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
16550 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
16560 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
16570 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
16580 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
16590 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
165a0 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
165b0 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
165c0 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
165d0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
165e0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
165f0 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
16600 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
16610 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
16620 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
16630 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
16640 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  f a table..**.**
16650 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
16660 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
16670 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
16680 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
16690 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
166a0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
166b0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
166c0 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 54  r() interface. T
166d0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
166e0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
166f0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
16700 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
16710 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
16720 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
16730 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
16740 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
16750 75 74 68 6f 72 69 7a 65 64 2e 20 54 68 65 20 74  uthorized. The t
16760 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
16770 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  th parameters.**
16780 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
16790 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
167a0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
167b0 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69  t contain additi
167c0 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20  onal.** details 
167d0 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
167e0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
167f0 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  d..**.** An auth
16800 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
16810 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
16820 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
16830 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
16840 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
16850 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
16860 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
16870 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
16880 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
16890 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
168a0 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
168b0 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
168c0 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
168d0 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
168e0 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
168f0 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
16900 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
16910 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
16920 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
16930 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
16940 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
16950 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
16960 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
16970 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
16980 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
16990 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
169a0 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
169b0 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
169c0 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
169d0 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
169e0 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
169f0 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
16a00 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
16a10 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
16a20 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
16a30 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
16a40 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
16a50 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
16a60 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
16a70 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
16a80 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
16a90 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
16aa0 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
16ab0 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
16ac0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
16ad0 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
16ae0 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
16af0 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
16b00 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
16b10 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
16b20 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
16b30 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
16b40 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
16b50 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
16b60 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
16b70 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
16b80 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20  r..**.** Only a 
16b90 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
16ba0 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
16bb0 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
16bc0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
16bd0 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
16be0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
16bf0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
16c00 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
16c10 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44  revious call.  D
16c20 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f  isable the autho
16c30 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c  rizer by install
16c40 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62  ing a NULL callb
16c50 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ack..** The auth
16c60 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  orizer is disabl
16c70 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
16c80 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
16c90 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
16ca0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
16cb0 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
16cc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
16cd0 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
16ce0 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
16cf0 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
16d00 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
16d10 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
16d20 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
16d30 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
16d40 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
16d50 2a 20 7b 48 31 32 35 30 31 7d 20 54 68 65 20 5b  * {H12501} The [
16d60 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
16d70 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e 29 5d 20 69  orizer(D,...)] i
16d80 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
16d90 72 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  rs a.**         
16da0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
16db0 62 61 63 6b 20 77 69 74 68 20 64 61 74 61 62 61  back with databa
16dc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
16dd0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 32 7d 20  .**.** {H12502} 
16de0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
16df0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
16e00 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
16e10 65 6e 74 73 20 61 72 65 0a 2a 2a 20 20 20 20 20  ents are.**     
16e20 20 20 20 20 20 62 65 69 6e 67 20 63 6f 6d 70 69       being compi
16e30 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  led..**.** {H125
16e40 30 33 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f  03} If the autho
16e50 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
16e60 65 74 75 72 6e 73 20 61 6e 79 20 76 61 6c 75 65  eturns any value
16e70 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20   other than.**  
16e80 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
16e90 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
16ea0 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
16eb0 5f 44 45 4e 59 5d 2c 20 74 68 65 6e 0a 2a 2a 20  _DENY], then.** 
16ec0 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
16ed0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
16ee0 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
16ef0 74 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73  t call that caus
16f00 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ed.**          t
16f10 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
16f20 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68  llback to run sh
16f30 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  all fail with an
16f40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
16f50 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f  LITE_ERROR] erro
16f60 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 61 70  r code and an ap
16f70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20  propriate error 
16f80 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b  message..**.** {
16f90 48 31 32 35 30 34 7d 20 57 68 65 6e 20 74 68 65  H12504} When the
16fa0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
16fb0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
16fc0 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 20 6f 70  LITE_OK], the op
16fd0 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  eration.**      
16fe0 20 20 20 20 64 65 73 63 72 69 62 65 64 20 69 73      described is
16ff0 20 70 72 6f 63 65 73 73 65 64 20 6e 6f 72 6d 61   processed norma
17000 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  lly..**.** {H125
17010 30 35 7d 20 57 68 65 6e 20 74 68 65 20 61 75 74  05} When the aut
17020 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17030 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
17040 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 20  _DENY], the.**  
17050 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
17060 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
17070 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
17080 6c 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68  l that caused th
17090 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75  e.**          au
170a0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
170b0 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66  k to run shall f
170c0 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ail.**          
170d0 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f  with an [SQLITE_
170e0 45 52 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64  ERROR] error cod
170f0 65 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d  e and an error m
17100 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20 20 20  essage.**       
17110 20 20 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68     explaining th
17120 61 74 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  at access is den
17130 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  ied..**.** {H125
17140 30 36 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f  06} If the autho
17150 72 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20  rizer code (the 
17160 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
17170 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a   the authorizer.
17180 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
17190 62 61 63 6b 29 20 69 73 20 5b 53 51 4c 49 54 45  back) is [SQLITE
171a0 5f 52 45 41 44 5d 20 61 6e 64 20 74 68 65 20 61  _READ] and the a
171b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
171c0 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  ck returns.**   
171d0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49         [SQLITE_I
171e0 47 4e 4f 52 45 5d 2c 20 74 68 65 6e 20 74 68 65  GNORE], then the
171f0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
17200 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
17210 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ed to.**        
17220 20 20 69 6e 73 65 72 74 20 61 20 4e 55 4c 4c 20    insert a NULL 
17230 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
17240 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
17250 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
17260 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  ve.**          b
17270 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
17280 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
17290 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
172a0 20 7b 48 31 32 35 30 37 7d 20 49 66 20 74 68 65   {H12507} If the
172b0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65   authorizer code
172c0 20 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65   (the 2nd parame
172d0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
172e0 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  rizer.**        
172f0 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 61    callback) is a
17300 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  nything other th
17310 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  an [SQLITE_READ]
17320 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20  , then.**       
17330 20 20 20 61 20 72 65 74 75 72 6e 20 6f 66 20 5b     a return of [
17340 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 68  SQLITE_IGNORE] h
17350 61 73 20 74 68 65 20 73 61 6d 65 20 65 66 66 65  as the same effe
17360 63 74 20 61 73 20 5b 53 51 4c 49 54 45 5f 44 45  ct as [SQLITE_DE
17370 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  NY]..**.** {H125
17380 31 30 7d 20 54 68 65 20 66 69 72 73 74 20 70 61  10} The first pa
17390 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
173a0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
173b0 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a  ck is a copy of.
173c0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
173d0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
173e0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
173f0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
17400 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
17410 2a 2a 20 7b 48 31 32 35 31 31 7d 20 54 68 65 20  ** {H12511} The 
17420 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17430 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
17440 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
17450 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
17460 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
17470 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
17480 69 66 69 65 73 20 74 68 65 20 70 61 72 74 69 63  ifies the partic
17490 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a 2a 20 20  ular action.**  
174a0 20 20 20 20 20 20 20 20 74 6f 20 62 65 20 61 75          to be au
174b0 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
174c0 7b 48 31 32 35 31 32 7d 20 54 68 65 20 74 68 69  {H12512} The thi
174d0 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
174e0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
174f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 0a  he callback are.
17500 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
17510 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
17520 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
17530 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 64  .**          add
17540 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20  itional details 
17550 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
17560 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
17570 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 30  d..**.** {H12520
17580 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b  } Each call to [
17590 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
175a0 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65 72 72 69  orizer()] overri
175b0 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  des.**          
175c0 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 69  any previously i
175d0 6e 73 74 61 6c 6c 65 64 20 61 75 74 68 6f 72 69  nstalled authori
175e0 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  zer..**.** {H125
175f0 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75 74 68 6f  21} A NULL autho
17600 72 69 7a 65 72 20 6d 65 61 6e 73 20 74 68 61 74  rizer means that
17610 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61 74 69 6f   no authorizatio
17620 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  n.**          ca
17630 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
17640 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 32 32  d..**.** {H12522
17650 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 61 75  } The default au
17660 74 68 6f 72 69 7a 65 72 20 69 73 20 4e 55 4c 4c  thorizer is NULL
17670 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
17680 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
17690 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
176a0 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
176b0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
176c0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
176d0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
176e0 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
176f0 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
17700 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
17710 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
17720 43 6f 64 65 73 20 7b 48 31 32 35 39 30 7d 20 3c  Codes {H12590} <
17730 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  H12500>.**.** Th
17740 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
17750 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
17760 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
17770 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a  function] must.*
17780 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20  * return either 
17790 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f  [SQLITE_OK] or o
177a0 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20  ne of these two 
177b0 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64  constants in ord
177c0 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  er.** to signal 
177d0 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f  SQLite whether o
177e0 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e  r not the action
177f0 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20   is permitted.  
17800 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  See the.** [sqli
17810 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
17820 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
17830 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
17840 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
17850 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
17860 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17870 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
17880 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
17890 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
178a0 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
178b0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
178c0 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
178d0 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
178e0 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
178f0 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
17900 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
17910 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 20  er Action Codes 
17920 7b 48 31 32 35 35 30 7d 20 3c 48 31 32 35 30 30  {H12550} <H12500
17930 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  >.**.** The [sql
17940 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
17950 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
17960 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
17970 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
17980 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
17990 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
179a0 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
179b0 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
179c0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
179d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
179e0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
179f0 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
17a00 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
17a10 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
17a20 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
17a30 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
17a40 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
17a50 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
17a60 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17a70 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
17a80 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
17a90 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
17aa0 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
17ab0 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
17ac0 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
17ad0 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
17ae0 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
17af0 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
17b00 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
17b10 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
17b20 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
17b30 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
17b40 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
17b50 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
17b60 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
17b70 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
17b80 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
17b90 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
17ba0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
17bb0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
17bc0 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
17bd0 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74  ", "temp",.** et
17be0 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
17bf0 65 2e 20 20 54 68 65 20 36 74 68 20 70 61 72 61  e.  The 6th para
17c00 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
17c10 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17c20 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
17c30 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
17c40 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
17c50 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
17c60 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
17c70 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
17c80 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
17c90 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
17ca0 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
17cb0 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
17cc0 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56   code..**.** INV
17cd0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
17ce0 48 31 32 35 35 31 7d 20 54 68 65 20 73 65 63 6f  H12551} The seco
17cf0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
17d00 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  an.**          [
17d10 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
17d20 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
17d30 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73  zer callback] is
17d40 20 61 6c 77 61 79 73 20 61 6e 20 69 6e 74 65 67   always an integ
17d50 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  er.**          [
17d60 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 75  SQLITE_COPY | au
17d70 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20 74  thorizer code] t
17d80 68 61 74 20 73 70 65 63 69 66 69 65 73 20 77 68  hat specifies wh
17d90 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  at action.**    
17da0 20 20 20 20 20 20 69 73 20 62 65 69 6e 67 20 61        is being a
17db0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
17dc0 20 7b 48 31 32 35 35 32 7d 20 54 68 65 20 33 72   {H12552} The 3r
17dd0 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
17de0 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 20  ters to the.**  
17df0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
17e00 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
17e10 7c 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  | authorization 
17e20 63 61 6c 6c 62 61 63 6b 5d 0a 2a 2a 20 20 20 20  callback].**    
17e30 20 20 20 20 20 20 77 69 6c 6c 20 62 65 20 70 61        will be pa
17e40 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
17e50 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
17e60 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ich.**          
17e70 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
17e80 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 5d 20  uthorizer code] 
17e90 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
17ea0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
17eb0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 33 7d 20  .**.** {H12553} 
17ec0 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
17ed0 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  r to the.**     
17ee0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65       [sqlite3_se
17ef0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
17f00 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
17f10 63 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d 65 0a  ck] is the name.
17f20 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  **          of t
17f30 68 65 20 64 61 74 61 62 61 73 65 20 28 65 78 61  he database (exa
17f40 6d 70 6c 65 3a 20 22 6d 61 69 6e 22 2c 20 22 74  mple: "main", "t
17f50 65 6d 70 22 2c 20 65 74 63 2e 29 20 69 66 20 61  emp", etc.) if a
17f60 70 70 6c 69 63 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  pplicable..**.**
17f70 20 7b 48 31 32 35 35 34 7d 20 54 68 65 20 36 74   {H12554} The 6t
17f80 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
17f90 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
17fa0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
17fb0 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
17fc0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73  zer callback] is
17fd0 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20   the name.**    
17fe0 20 20 20 20 20 20 6f 66 20 74 68 65 20 69 6e 6e        of the inn
17ff0 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
18000 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
18010 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
18020 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
18030 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
18040 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
18050 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
18060 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
18070 2a 20 20 20 20 20 20 20 20 20 20 74 6f 70 2d 6c  *          top-l
18080 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
18090 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
180a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
180b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
180c0 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
180d0 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
180e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
180f0 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
18100 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
18110 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
18120 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
18130 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18140 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
18150 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
18160 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
18170 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
18180 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
18190 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
181a0 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
181b0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
181c0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
181d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
181e0 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
181f0 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
18200 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
18210 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
18220 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
18230 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
18240 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
18250 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
18260 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
18270 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
18280 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
18290 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
182a0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
182b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
182c0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
182d0 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
182e0 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
182f0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
18300 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
18310 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
18320 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
18330 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
18340 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18350 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18360 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
18370 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
18380 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
18390 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
183a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
183b0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
183c0 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
183d0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
183e0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
183f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18400 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
18410 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
18420 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
18430 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
18440 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18450 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
18460 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
18470 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
18480 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
18490 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
184a0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
184b0 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
184c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
184d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
184e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
184f0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
18500 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
18510 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
18520 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18530 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18540 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
18550 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
18560 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
18570 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18580 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18590 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
185a0 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
185b0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
185c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
185d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
185e0 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
185f0 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
18600 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
18610 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18620 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
18630 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
18640 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
18650 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
18660 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
18670 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
18680 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
18690 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
186a0 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
186b0 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
186c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
186d0 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
186e0 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
186f0 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
18700 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
18710 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
18720 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
18730 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
18740 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
18750 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18760 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
18770 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
18780 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  22   /* NULL    
18790 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
187a0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
187b0 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
187c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
187d0 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
187e0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
187f0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
18800 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
18810 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
18820 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
18830 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18840 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18850 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
18860 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
18870 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
18880 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
18890 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
188a0 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
188b0 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
188c0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
188d0 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
188e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
188f0 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
18900 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
18910 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
18920 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
18930 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18940 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
18950 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
18960 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
18970 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18980 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18990 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
189a0 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
189b0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
189c0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
189d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
189e0 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
189f0 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
18a00 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18a10 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
18a20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18a30 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
18a40 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 46         31   /* F
18a50 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 4e  unction Name   N
18a60 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18a70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18a80 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
18a90 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
18aa0 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
18ab0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18ac0 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f   Tracing And Pro
18ad0 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  filing Functions
18ae0 20 7b 48 31 32 32 38 30 7d 20 3c 53 36 30 34 30   {H12280} <S6040
18af0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
18b00 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
18b10 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
18b20 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
18b30 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
18b40 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
18b50 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
18b60 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
18b70 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  s..**.** The cal
18b80 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
18b90 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
18ba0 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
18bb0 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
18bc0 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
18bd0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
18be0 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
18bf0 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
18c00 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  )]..** The callb
18c10 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 55 54  ack returns a UT
18c20 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
18c30 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
18c40 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73 20 74 68  nt text.** as th
18c50 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
18c60 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
18c70 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  ng.  Additional 
18c80 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a  callbacks occur.
18c90 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
18ca0 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
18cb0 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
18cc0 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
18cd0 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
18ce0 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
18cf0 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
18d00 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
18d10 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  er..**.** The ca
18d20 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
18d30 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
18d40 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
18d50 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
18d60 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
18d70 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 54  ent finishes.  T
18d80 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
18d90 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
18da0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
18db0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
18dc0 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
18dd0 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
18de0 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
18df0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
18e00 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20  k to run..**.** 
18e10 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  The sqlite3_prof
18e20 69 6c 65 28 29 20 41 50 49 20 69 73 20 63 75 72  ile() API is cur
18e30 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65  rently considere
18e40 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
18e50 6e 64 0a 2a 2a 20 69 73 20 73 75 62 6a 65 63 74  nd.** is subject
18e60 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72 65   to change or re
18e70 6d 6f 76 61 6c 20 69 6e 20 61 20 66 75 74 75 72  moval in a futur
18e80 65 20 72 65 6c 65 61 73 65 2e 0a 2a 2a 0a 2a 2a  e release..**.**
18e90 20 54 68 65 20 74 72 69 67 67 65 72 20 72 65 70   The trigger rep
18ea0 6f 72 74 69 6e 67 20 66 65 61 74 75 72 65 20 6f  orting feature o
18eb0 66 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c  f the trace call
18ec0 62 61 63 6b 20 69 73 20 63 6f 6e 73 69 64 65 72  back is consider
18ed0 65 64 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74  ed.** experiment
18ee0 61 6c 20 61 6e 64 20 69 73 20 73 75 62 6a 65 63  al and is subjec
18ef0 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72 20 72  t to change or r
18f00 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74 75 72 65  emoval in future
18f10 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 20 46 75   releases..** Fu
18f20 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
18f30 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c   SQLite might al
18f40 73 6f 20 61 64 64 20 6e 65 77 20 74 72 61 63 65  so add new trace
18f50 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6e 76   callback.** inv
18f60 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  ocations..**.** 
18f70 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
18f80 2a 20 7b 48 31 32 32 38 31 7d 20 54 68 65 20 63  * {H12281} The c
18f90 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
18fa0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b   registered by [
18fb0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d  sqlite3_trace()]
18fc0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
18fd0 77 68 65 6e 65 76 65 72 20 61 6e 20 53 51 4c 20  whenever an SQL 
18fe0 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
18ff0 62 65 67 69 6e 73 20 74 6f 20 65 78 65 63 75 74  begins to execut
19000 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  e and.**        
19010 20 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 69    whenever a tri
19020 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 20  gger subprogram 
19030 66 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20  first begins to 
19040 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  run..**.** {H122
19050 38 32 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  82} Each call to
19060 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
19070 29 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  )] overrides the
19080 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20   previously.**  
19090 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
190a0 65 64 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ed trace callbac
190b0 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 33  k..**.** {H12283
190c0 7d 20 41 20 4e 55 4c 4c 20 74 72 61 63 65 20 63  } A NULL trace c
190d0 61 6c 6c 62 61 63 6b 20 64 69 73 61 62 6c 65 73  allback disables
190e0 20 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   tracing..**.** 
190f0 7b 48 31 32 32 38 34 7d 20 54 68 65 20 66 69 72  {H12284} The fir
19100 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
19110 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  he trace callbac
19120 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  k is a copy of.*
19130 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 70  *          the p
19140 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73  ointer which was
19150 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e   the 3rd argumen
19160 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72  t to [sqlite3_tr
19170 61 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ace()]..**.** {H
19180 31 32 32 38 35 7d 20 54 68 65 20 73 65 63 6f 6e  12285} The secon
19190 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
191a0 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  e trace callback
191b0 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20   is a.**        
191c0 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
191d0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 63  d UTF-8 string c
191e0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6f 72  ontaining the or
191f0 69 67 69 6e 61 6c 20 74 65 78 74 0a 2a 2a 20 20  iginal text.**  
19200 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 53          of the S
19210 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
19220 69 74 20 77 61 73 20 70 61 73 73 65 64 20 69 6e  it was passed in
19230 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
19240 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20  are_v2()].**    
19250 20 20 20 20 20 20 6f 72 20 74 68 65 20 65 71 75        or the equ
19260 69 76 61 6c 65 6e 74 2c 20 6f 72 20 61 6e 20 53  ivalent, or an S
19270 51 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e 64 69 63  QL comment indic
19280 61 74 69 6e 67 20 74 68 65 20 62 65 67 69 6e 6e  ating the beginn
19290 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
192a0 6f 66 20 61 20 74 72 69 67 67 65 72 20 73 75 62  of a trigger sub
192b0 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b  program..**.** {
192c0 48 31 32 32 38 37 7d 20 54 68 65 20 63 61 6c 6c  H12287} The call
192d0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
192e0 67 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c  gistered by [sql
192f0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20  ite3_profile()] 
19300 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20  is invoked.**   
19310 20 20 20 20 20 20 20 61 73 20 65 61 63 68 20 53         as each S
19320 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
19330 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ishes..**.** {H1
19340 32 32 38 38 7d 20 54 68 65 20 66 69 72 73 74 20  2288} The first 
19350 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
19360 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
19370 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  k is a copy of.*
19380 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 33  *          the 3
19390 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
193a0 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  [sqlite3_profile
193b0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  ()]..**.** {H122
193c0 38 39 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70  89} The second p
193d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
193e0 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
193f0 20 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20   is a.**        
19400 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65    zero-terminate
19410 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  d UTF-8 string t
19420 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  hat contains the
19430 20 63 6f 6d 70 6c 65 74 65 20 74 65 78 74 20 6f   complete text o
19440 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
19450 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
19460 61 73 20 69 74 20 77 61 73 20 70 72 6f 63 65 73  as it was proces
19470 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
19480 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a  prepare_v2()].**
19490 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65            or the
194a0 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a   equivalent..**.
194b0 2a 2a 20 7b 48 31 32 32 39 30 7d 20 54 68 65 20  ** {H12290} The 
194c0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
194d0 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63  to the profile c
194e0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 65 73  allback is an es
194f0 74 69 6d 61 74 65 0a 2a 2a 20 20 20 20 20 20 20  timate.**       
19500 20 20 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72     of the number
19510 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 20   of nanoseconds 
19520 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
19530 6d 65 20 72 65 71 75 69 72 65 64 20 74 6f 0a 2a  me required to.*
19540 2a 20 20 20 20 20 20 20 20 20 20 72 75 6e 20 74  *          run t
19550 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
19560 20 66 72 6f 6d 20 73 74 61 72 74 20 74 6f 20 66   from start to f
19570 69 6e 69 73 68 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  inish..*/.void *
19580 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
19590 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54  lite3*, void(*xT
195a0 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
195b0 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
195c0 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
195d0 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
195e0 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
195f0 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
19600 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
19610 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
19620 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19630 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
19640 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 31  Callbacks {H1291
19650 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a  0} <S60400>.**.*
19660 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63  * This routine c
19670 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c  onfigures a call
19680 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20  back function - 
19690 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20  the.** progress 
196a0 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20  callback - that 
196b0 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  is invoked perio
196c0 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
196d0 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63  ong.** running c
196e0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
196f0 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
19700 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a  e3_step()] and.*
19710 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
19720 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61  able()].  An exa
19730 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
19740 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
19750 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
19760 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
19770 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
19780 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72  .** If the progr
19790 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
197a0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
197b0 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
197c0 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
197d0 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
197e0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
197f0 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
19800 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
19810 20 47 55 49 20 64 69 61 6c 6f 67 20 62 6f 78 2e   GUI dialog box.
19820 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
19830 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 31  S:.**.** {H12911
19840 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  } The callback f
19850 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
19860 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
19870 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29  ogress_handler()
19880 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
19890 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
198a0 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
198b0 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
198c0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
198d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
198e0 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 32 7d 20 54  **.** {H12912} T
198f0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
19900 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
19910 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20 4e  once for every N
19920 20 76 69 72 74 75 61 6c 0a 2a 2a 20 20 20 20 20   virtual.**     
19930 20 20 20 20 20 6d 61 63 68 69 6e 65 20 6f 70 63       machine opc
19940 6f 64 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  odes, where N is
19950 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
19960 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20  ment to.**      
19970 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33      the [sqlite3
19980 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
19990 72 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 72  r()] call that r
199a0 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20 20  egistered.**    
199b0 20 20 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61        the callba
199c0 63 6b 2e 20 20 49 66 20 4e 20 69 73 20 6c 65 73  ck.  If N is les
199d0 73 20 74 68 61 6e 20 31 2c 20 73 71 6c 69 74 65  s than 1, sqlite
199e0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
199f0 65 72 28 29 0a 2a 2a 20 20 20 20 20 20 20 20 20  er().**         
19a00 20 61 63 74 73 20 61 73 20 69 66 20 61 20 4e 55   acts as if a NU
19a10 4c 4c 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  LL progress hand
19a20 6c 65 72 20 68 61 64 20 62 65 65 6e 20 73 70 65  ler had been spe
19a30 63 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  cified..**.** {H
19a40 31 32 39 31 33 7d 20 54 68 65 20 70 72 6f 67 72  12913} The progr
19a50 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 74 73  ess callback its
19a60 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66 69 65  elf is identifie
19a70 64 20 62 79 20 74 68 65 20 74 68 69 72 64 0a 2a  d by the third.*
19a80 2a 20 20 20 20 20 20 20 20 20 20 61 72 67 75 6d  *          argum
19a90 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70  ent to sqlite3_p
19aa0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
19ab0 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 34  )..**.** {H12914
19ac0 7d 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  } The fourth arg
19ad0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
19ae0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
19af0 72 28 29 20 69 73 20 61 0a 2a 2a 20 20 20 20 20  r() is a.**     
19b00 20 20 20 20 20 76 6f 69 64 20 70 6f 69 6e 74 65       void pointe
19b10 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
19b20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
19b30 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75  k.**          fu
19b40 6e 63 74 69 6f 6e 20 65 61 63 68 20 74 69 6d 65  nction each time
19b50 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a   it is invoked..
19b60 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 35 7d 20 49  **.** {H12915} I
19b70 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  f a call to [sql
19b80 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 73  ite3_step()] res
19b90 75 6c 74 73 20 69 6e 20 66 65 77 65 72 20 74 68  ults in fewer th
19ba0 61 6e 20 4e 20 6f 70 63 6f 64 65 73 0a 2a 2a 20  an N opcodes.** 
19bb0 20 20 20 20 20 20 20 20 20 62 65 69 6e 67 20 65           being e
19bc0 78 65 63 75 74 65 64 2c 20 74 68 65 6e 20 74 68  xecuted, then th
19bd0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
19be0 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e 76  ack is never inv
19bf0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  oked..**.** {H12
19c00 39 31 36 7d 20 45 76 65 72 79 20 63 61 6c 6c 20  916} Every call 
19c10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67  to [sqlite3_prog
19c20 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 0a  ress_handler()].
19c30 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 72  **          over
19c40 77 72 69 74 65 73 20 61 6e 79 20 70 72 65 76 69  writes any previ
19c50 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64  ously registered
19c60 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
19c70 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 37  r..**.** {H12917
19c80 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65 73  } If the progres
19c90 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  s handler callba
19ca0 63 6b 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  ck is NULL then 
19cb0 6e 6f 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 20  no progress.**  
19cc0 20 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20          handler 
19cd0 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
19ce0 2a 20 7b 48 31 32 39 31 38 7d 20 49 66 20 74 68  * {H12918} If th
19cf0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
19d00 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 72 65  ack returns a re
19d10 73 75 6c 74 20 6f 74 68 65 72 20 74 68 61 6e 20  sult other than 
19d20 30 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  0, then.**      
19d30 20 20 20 20 74 68 65 20 62 65 68 61 76 69 6f 72      the behavior
19d40 20 69 73 20 61 20 69 66 20 5b 73 71 6c 69 74 65   is a if [sqlite
19d50 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20 68  3_interrupt()] h
19d60 61 64 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a  ad been called..
19d70 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 53 33 30  **          <S30
19d80 35 30 30 3e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  500>.*/.void sql
19d90 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
19da0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
19db0 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
19dc0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
19dd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
19de0 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
19df0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b  ase Connection {
19e00 48 31 32 37 30 30 7d 20 3c 53 34 30 32 30 30 3e  H12700} <S40200>
19e10 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
19e20 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
19e30 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
19e40 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73  le whose name is
19e50 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a   given by the.**
19e60 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
19e70 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61 6d 65  nt. The filename
19e80 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
19e90 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
19ea0 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
19eb0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
19ec0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
19ed0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
19ee0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
19ef0 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
19f00 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 41 20  te3_open16(). A 
19f10 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
19f20 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20  tion] handle is 
19f30 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72  usually.** retur
19f40 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
19f50 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  en if an error o
19f60 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79  ccurs.  The only
19f70 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68   exception is th
19f80 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  at.** if SQLite 
19f90 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
19fa0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
19fb0 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65  hold the [sqlite
19fc0 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20  3] object,.** a 
19fd0 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69  NULL will be wri
19fe0 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20  tten into *ppDb 
19ff0 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69  instead of a poi
1a000 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
1a010 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e  ite3].** object.
1a020 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
1a030 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f   is opened (and/
1a040 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63  or created) succ
1a050 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a  essfully, then.*
1a060 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  * [SQLITE_OK] is
1a070 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
1a080 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
1a090 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
1a0a0 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  d.  The.** [sqli
1a0b0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
1a0c0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1a0d0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
1a0e0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
1a0f0 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
1a100 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
1a110 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
1a120 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rror..**.** The 
1a130 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
1a140 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
1a150 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20  e will be UTF-8 
1a160 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  if.** sqlite3_op
1a170 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
1a180 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c  open_v2() is cal
1a190 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31  led and.** UTF-1
1a1a0 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
1a1b0 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73 71  byte order if sq
1a1c0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69  lite3_open16() i
1a1d0 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68  s used..**.** Wh
1a1e0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20  ether or not an 
1a1f0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65  error occurs whe
1a200 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20  n it is opened, 
1a210 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73  resources.** ass
1a220 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
1a230 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1a240 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68  ction] handle sh
1a250 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
1a260 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69   by.** passing i
1a270 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  t to [sqlite3_cl
1a280 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
1a290 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
1a2a0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
1a2b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1a2c0 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b  ) interface work
1a2d0 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f  s like sqlite3_o
1a2e0 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  pen().** except 
1a2f0 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20  that it accepts 
1a300 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70  two additional p
1a310 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64  arameters for ad
1a320 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c  ditional control
1a330 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77  .** over the new
1a340 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a350 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67 73  tion.  The flags
1a360 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 74   parameter can t
1a370 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
1a380 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
1a390 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
1a3a0 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
1a3b0 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
1a3c0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1a3d0 20 66 6c 61 67 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c   flag:.**.** <dl
1a3e0 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45  >.** <dt>[SQLITE
1a3f0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
1a400 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1a410 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1a420 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
1a430 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
1a440 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
1a450 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
1a460 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
1a470 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  turned.</dd>.**.
1a480 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f  ** <dt>[SQLITE_O
1a490 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f  PEN_READWRITE]</
1a4a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
1a4b0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1a4c0 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
1a4d0 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
1a4e0 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e  sible, or readin
1a4f0 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65  g.** only if the
1a500 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
1a510 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
1a520 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1a530 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20  .  In either.** 
1a540 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
1a550 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65  e must already e
1a560 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20  xist, otherwise 
1a570 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
1a580 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  rned.</dd>.**.**
1a590 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45   <dt>[SQLITE_OPE
1a5a0 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
1a5b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1a5c0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
1a5d0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1a5e0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
1a5f0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20  ng and writing, 
1a600 61 6e 64 20 69 73 20 63 72 65 61 74 65 73 20 69  and is creates i
1a610 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  t if.** it does 
1a620 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
1a630 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
1a640 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
1a650 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
1a660 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
1a670 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
1a680 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20  en16().</dd>.** 
1a690 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
1a6a0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
1a6b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
1a6c0 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
1a6d0 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
1a6e0 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
1a6f0 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ove or one of th
1a700 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  e combinations s
1a710 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69  hown above combi
1a720 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ned.** with the 
1a730 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1a740 55 54 45 58 5d 20 66 6c 61 67 2c 20 74 68 65 6e  UTEX] flag, then
1a750 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1a760 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
1a770 2a 20 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * If the [SQLITE
1a780 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
1a790 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e  lag is set, then
1a7a0 20 6d 75 74 65 78 65 73 20 6f 6e 20 74 68 65 0a   mutexes on the.
1a7b0 2a 2a 20 6f 70 65 6e 65 64 20 5b 64 61 74 61 62  ** opened [datab
1a7c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1a7d0 61 72 65 20 64 69 73 61 62 6c 65 64 20 61 6e 64  are disabled and
1a7e0 20 74 68 65 20 61 70 70 6c 69 61 74 69 6f 6e 20   the appliation 
1a7f0 6d 75 73 74 0a 2a 2a 20 69 6e 73 75 72 65 20 74  must.** insure t
1a800 68 61 74 20 61 63 63 65 73 73 20 74 6f 20 74 68  hat access to th
1a810 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1a820 65 63 74 69 6f 6e 5d 20 61 6e 64 20 69 74 73 20  ection] and its 
1a830 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 5b 70  associated.** [p
1a840 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1a850 74 73 5d 20 69 73 20 73 65 72 69 61 6c 69 7a 65  ts] is serialize
1a860 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
1a870 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
1a880 61 67 0a 2a 2a 20 69 73 20 74 68 65 20 64 65 66  ag.** is the def
1a890 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73  ault behavior is
1a8a0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6e 66 69   SQLite is confi
1a8b0 67 75 72 65 64 20 75 73 69 6e 67 20 74 68 65 0a  gured using the.
1a8c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
1a8d0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 20 6f  G_MULTITHREAD] o
1a8e0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
1a8f0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
1a900 70 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 5b 73 71  ptions.** to [sq
1a910 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
1a920 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50    The [SQLITE_OP
1a930 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
1a940 20 6f 6e 6c 79 20 6d 61 6b 65 73 20 61 0a 2a 2a   only makes a.**
1a950 20 64 69 66 66 65 72 65 6e 63 65 20 77 68 65 6e   difference when
1a960 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 69 74   SQLite is in it
1a970 73 20 64 65 66 61 75 6c 74 20 5b 53 51 4c 49 54  s default [SQLIT
1a980 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
1a990 5a 45 44 5d 20 6d 6f 64 65 2e 0a 2a 2a 0a 2a 2a  ZED] mode..**.**
1a9a0 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   If the filename
1a9b0 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
1a9c0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
1a9d0 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
1a9e0 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
1a9f0 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
1aa00 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
1aa10 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
1aa20 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
1aa30 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
1aa40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1aa50 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
1aa60 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
1aa70 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
1aa80 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
1aa90 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
1aaa0 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
1aab0 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
1aac0 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
1aad0 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
1aae0 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
1aaf0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
1ab00 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
1ab10 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
1ab20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
1ab30 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
1ab40 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
1ab50 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
1ab60 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
1ab70 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
1ab80 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  .**.** If the fi
1ab90 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
1aba0 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
1abb0 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
1abc0 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
1abd0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1abe0 20 63 72 65 61 74 65 64 2e 20 20 54 68 69 73 20   created.  This 
1abf0 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
1ac00 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
1ac10 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
1ac20 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
1ac30 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1ac40 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
1ac50 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68  **.** The fourth
1ac60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1ac70 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1ac80 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1ac90 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
1aca0 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
1acb0 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
1acc0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
1acd0 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74  erface that.** t
1ace0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
1acf0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
1ad00 64 20 75 73 65 2e 20 20 49 66 20 74 68 65 20 66  d use.  If the f
1ad10 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1ad20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
1ad30 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
1ad40 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
1ad50 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
1ad60 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
1ad70 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
1ad80 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
1ad90 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
1ada0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
1adb0 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
1adc0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1add0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1ade0 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
1adf0 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
1ae00 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
1ae10 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
1ae20 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
1ae30 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
1ae40 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
1ae50 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
1ae60 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
1ae70 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
1ae80 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
1ae90 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
1aea0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
1aeb0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1aec0 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 31 7d 20 54  **.** {H12701} T
1aed0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
1aee0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1aef0 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
1af00 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1af10 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
1af20 65 72 66 61 63 65 73 20 63 72 65 61 74 65 20 61  erfaces create a
1af30 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20   new.**         
1af40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1af50 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65  ction] associate
1af60 64 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  d with.**       
1af70 20 20 20 74 68 65 20 64 61 74 61 62 61 73 65 20     the database 
1af80 66 69 6c 65 20 67 69 76 65 6e 20 69 6e 20 74 68  file given in th
1af90 65 69 72 20 66 69 72 73 74 20 70 61 72 61 6d 65  eir first parame
1afa0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ter..**.** {H127
1afb0 30 32 7d 20 54 68 65 20 66 69 6c 65 6e 61 6d 65  02} The filename
1afc0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
1afd0 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
1afe0 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f  8.**          fo
1aff0 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  r [sqlite3_open(
1b000 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1b010 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e 64 20 61  open_v2()] and a
1b020 73 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20 20  s UTF-16.**     
1b030 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74 69       in the nati
1b040 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f  ve byte order fo
1b050 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
1b060 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  6()]..**.** {H12
1b070 37 30 33 7d 20 41 20 73 75 63 63 65 73 73 66 75  703} A successfu
1b080 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
1b090 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1b0a0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
1b0b0 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  6()],.**        
1b0c0 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70    or [sqlite3_op
1b0d0 65 6e 5f 76 32 28 29 5d 20 77 72 69 74 65 73 20  en_v2()] writes 
1b0e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
1b0f0 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ew.**          [
1b100 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b110 69 6f 6e 5d 20 69 6e 74 6f 20 2a 70 70 44 62 2e  ion] into *ppDb.
1b120 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 34 7d 20  .**.** {H12704} 
1b130 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
1b140 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
1b150 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a  pen16()], and.**
1b160 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1b170 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
1b180 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20  terfaces return 
1b190 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 75 70 6f 6e  [SQLITE_OK] upon
1b1a0 20 73 75 63 63 65 73 73 2c 0a 2a 2a 20 20 20 20   success,.**    
1b1b0 20 20 20 20 20 20 6f 72 20 61 6e 20 61 70 70 72        or an appr
1b1c0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
1b1d0 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72 65 2e  ode] on failure.
1b1e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 36 7d 20  .**.** {H12706} 
1b1f0 54 68 65 20 64 65 66 61 75 6c 74 20 74 65 78 74  The default text
1b200 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20   encoding for a 
1b210 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 72 65  new database cre
1b220 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ated using.**   
1b230 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1b240 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69  open()] or [sqli
1b250 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77  te3_open_v2()] w
1b260 69 6c 6c 20 62 65 20 55 54 46 2d 38 2e 0a 2a 2a  ill be UTF-8..**
1b270 0a 2a 2a 20 7b 48 31 32 37 30 37 7d 20 54 68 65  .** {H12707} The
1b280 20 64 65 66 61 75 6c 74 20 74 65 78 74 20 65 6e   default text en
1b290 63 6f 64 69 6e 67 20 66 6f 72 20 61 20 6e 65 77  coding for a new
1b2a0 20 64 61 74 61 62 61 73 65 20 63 72 65 61 74 65   database create
1b2b0 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20  d using.**      
1b2c0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65      [sqlite3_ope
1b2d0 6e 31 36 28 29 5d 20 77 69 6c 6c 20 62 65 20 55  n16()] will be U
1b2e0 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  TF-16..**.** {H1
1b2f0 32 37 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74  2709} The [sqlit
1b300 65 33 5f 6f 70 65 6e 28 46 2c 44 29 5d 20 69 6e  e3_open(F,D)] in
1b310 74 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76  terface is equiv
1b320 61 6c 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20  alent to.**     
1b330 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70       [sqlite3_op
1b340 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 30 29 5d 20  en_v2(F,D,G,0)] 
1b350 77 68 65 72 65 20 74 68 65 20 47 20 70 61 72 61  where the G para
1b360 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20  meter is.**     
1b370 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45       [SQLITE_OPE
1b380 4e 5f 52 45 41 44 57 52 49 54 45 5d 7c 5b 53 51  N_READWRITE]|[SQ
1b390 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1b3a0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 31  ]..**.** {H12711
1b3b0 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d  } If the G param
1b3c0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1b3d0 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56  _open_v2(F,D,G,V
1b3e0 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a  )] contains the.
1b3f0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20  **          bit 
1b400 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50  value [SQLITE_OP
1b410 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 74 68 65  EN_READONLY] the
1b420 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
1b430 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20  s opened.**     
1b440 20 20 20 20 20 66 6f 72 20 72 65 61 64 69 6e 67       for reading
1b450 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   only..**.** {H1
1b460 32 37 31 32 7d 20 49 66 20 74 68 65 20 47 20 70  2712} If the G p
1b470 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
1b480 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
1b490 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20  ,G,V)] contains 
1b4a0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1b4b0 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  bit value [SQLIT
1b4c0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1b4d0 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  ] then the datab
1b4e0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a  ase is opened.**
1b4f0 20 20 20 20 20 20 20 20 20 20 72 65 61 64 69 6e            readin
1b500 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
1b510 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 66 6f   possible, or fo
1b520 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 20 69  r reading only i
1b530 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
1b540 20 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20    file is write 
1b550 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
1b560 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1b570 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 33  m..**.** {H12713
1b580 7d 20 49 66 20 74 68 65 20 47 20 70 61 72 61 6d  } If the G param
1b590 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1b5a0 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c 47 2c 56  _open(v2(F,D,G,V
1b5b0 29 5d 20 6f 6d 69 74 73 20 74 68 65 0a 2a 2a 20  )] omits the.** 
1b5c0 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c           bit val
1b5d0 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ue [SQLITE_OPEN_
1b5e0 43 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20  CREATE] and the 
1b5f0 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
1b600 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72  t.**          pr
1b610 65 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20  eviously exist, 
1b620 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
1b630 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  rned..**.** {H12
1b640 37 31 34 7d 20 49 66 20 74 68 65 20 47 20 70 61  714} If the G pa
1b650 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
1b660 74 65 33 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c  te3_open(v2(F,D,
1b670 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74  G,V)] contains t
1b680 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  he.**          b
1b690 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  it value [SQLITE
1b6a0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e  _OPEN_CREATE] an
1b6b0 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64  d the database d
1b6c0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20  oes not.**      
1b6d0 20 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65      previously e
1b6e0 78 69 73 74 2c 20 74 68 65 6e 20 61 6e 20 61 74  xist, then an at
1b6f0 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
1b700 20 63 72 65 61 74 65 20 61 6e 64 0a 2a 2a 20 20   create and.**  
1b710 20 20 20 20 20 20 20 20 69 6e 69 74 69 61 6c 69          initiali
1b720 7a 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ze the database.
1b730 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 37 7d 20  .**.** {H12717} 
1b740 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1b750 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
1b760 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1b770 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1b780 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
1b790 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1b7a0 32 28 29 5d 20 69 73 20 22 3a 6d 65 6d 6f 72 79  2()] is ":memory
1b7b0 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70 72 69 76  :", then an priv
1b7c0 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ate,.**         
1b7d0 20 65 70 68 65 6d 65 72 61 6c 2c 20 69 6e 2d 6d   ephemeral, in-m
1b7e0 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 69  emory database i
1b7f0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
1b800 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a  e connection..**
1b810 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e            <todo>
1b820 49 73 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  Is SQLITE_OPEN_C
1b830 52 45 41 54 45 7c 53 51 4c 49 54 45 5f 4f 50 45  REATE|SQLITE_OPE
1b840 4e 5f 52 45 41 44 57 52 49 54 45 20 72 65 71 75  N_READWRITE requ
1b850 69 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ired.**         
1b860 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   in sqlite3_open
1b870 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a  _v2()?</todo>.**
1b880 0a 2a 2a 20 7b 48 31 32 37 31 39 7d 20 49 66 20  .** {H12719} If 
1b890 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
1b8a0 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79  NULL or an empty
1b8b0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
1b8c0 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20  private,.**     
1b8d0 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c 20 6f       ephemeral o
1b8e0 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
1b8f0 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
1b900 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f  .**          <to
1b910 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 45  do>Is SQLITE_OPE
1b920 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45 5f  N_CREATE|SQLITE_
1b930 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 72  OPEN_READWRITE r
1b940 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 20  equired.**      
1b950 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f      in sqlite3_o
1b960 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e  pen_v2()?</todo>
1b970 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32 31 7d 20  .**.** {H12721} 
1b980 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
1b990 6e 6e 65 63 74 69 6f 6e 5d 20 63 72 65 61 74 65  nnection] create
1b9a0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d by [sqlite3_op
1b9b0 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 0a  en_v2(F,D,G,V)].
1b9c0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c  **          will
1b9d0 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
1b9e0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 64  3_vfs] object id
1b9f0 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
1ba00 56 20 70 61 72 61 6d 65 74 65 72 2c 0a 2a 2a 20  V parameter,.** 
1ba10 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
1ba20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1ba30 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 66 20  _vfs] object if 
1ba40 56 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  V is a NULL poin
1ba50 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ter..**.** {H127
1ba60 32 33 7d 20 54 77 6f 20 5b 64 61 74 61 62 61 73  23} Two [databas
1ba70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 77  e connections] w
1ba80 69 6c 6c 20 73 68 61 72 65 20 61 20 63 6f 6d 6d  ill share a comm
1ba90 6f 6e 20 63 61 63 68 65 20 69 66 20 62 6f 74 68  on cache if both
1baa0 20 77 65 72 65 0a 2a 2a 20 20 20 20 20 20 20 20   were.**        
1bab0 20 20 6f 70 65 6e 65 64 20 77 69 74 68 20 74 68    opened with th
1bac0 65 20 73 61 6d 65 20 56 46 53 20 77 68 69 6c 65  e same VFS while
1bad0 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
1bae0 6f 64 65 5d 20 77 61 73 20 65 6e 61 62 6c 65 64  ode] was enabled
1baf0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
1bb00 20 69 66 20 62 6f 74 68 20 66 69 6c 65 6e 61 6d   if both filenam
1bb10 65 73 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c  es compare equal
1bb20 20 75 73 69 6e 67 20 6d 65 6d 63 6d 70 28 29 20   using memcmp() 
1bb30 61 66 74 65 72 20 68 61 76 69 6e 67 20 62 65 65  after having bee
1bb40 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72  n.**          pr
1bb50 6f 63 65 73 73 65 64 20 62 79 20 74 68 65 20 5b  ocessed by the [
1bb60 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 78 46  sqlite3_vfs | xF
1bb70 75 6c 6c 50 61 74 68 6e 61 6d 65 5d 20 6d 65 74  ullPathname] met
1bb80 68 6f 64 20 6f 66 20 74 68 65 20 56 46 53 2e 0a  hod of the VFS..
1bb90 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
1bba0 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
1bbb0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
1bbc0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
1bbd0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
1bbe0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
1bbf0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
1bc00 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
1bc10 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
1bc20 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
1bc30 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
1bc40 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
1bc50 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
1bc60 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
1bc70 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
1bc80 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
1bc90 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
1bca0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
1bcb0 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
1bcc0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
1bcd0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
1bce0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
1bcf0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
1bd00 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
1bd10 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
1bd20 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
1bd30 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1bd40 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
1bd50 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
1bd60 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
1bd70 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
1bd80 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
1bd90 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
1bda0 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
1bdb0 73 20 7b 48 31 32 38 30 30 7d 20 3c 53 36 30 32  s {H12800} <S602
1bdc0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
1bdd0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
1bde0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1bdf0 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
1be00 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a  esult code] or.*
1be10 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
1be20 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  lt code] for the
1be30 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69   most recent fai
1be40 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  led sqlite3_* AP
1be50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69  I call.** associ
1be60 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74  ated with a [dat
1be70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1be80 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50  ]. If a prior AP
1be90 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a  I call failed.**
1bea0 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65   but the most re
1beb0 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75  cent API call su
1bec0 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74  cceeded, the ret
1bed0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a  urn value from.*
1bee0 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  * sqlite3_errcod
1bef0 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
1bf00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1bf10 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64  te3_errmsg() and
1bf20 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31   sqlite3_errmsg1
1bf30 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69  6() return Engli
1bf40 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74  sh-language.** t
1bf50 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
1bf60 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73  es the error, as
1bf70 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
1bf80 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69   UTF-16 respecti
1bf90 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  vely..** Memory 
1bfa0 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
1bfb0 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
1bfc0 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
1bfd0 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61  rnally..** The a
1bfe0 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20  pplication does 
1bff0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72  not need to worr
1c000 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20  y about freeing 
1c010 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48  the result..** H
1c020 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f  owever, the erro
1c030 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62  r string might b
1c040 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
1c050 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a   deallocated by.
1c060 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ** subsequent ca
1c070 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c  lls to other SQL
1c080 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75  ite interface fu
1c090 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  nctions..**.** I
1c0a0 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
1c0b0 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
1c0c0 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
1c0d0 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
1c0e0 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
1c0f0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
1c100 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
1c110 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
1c120 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
1c130 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
1c140 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
1c150 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  set..**.** INVAR
1c160 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
1c170 32 38 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2801} The [sqlit
1c180 65 33 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69  e3_errcode(D)] i
1c190 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1c1a0 20 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20   the numeric.** 
1c1b0 20 20 20 20 20 20 20 20 20 5b 72 65 73 75 6c 74           [result
1c1c0 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e   code] or [exten
1c1d0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
1c1e0 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
1c1f0 63 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20  cently.**       
1c200 20 20 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66     failed interf
1c210 61 63 65 20 63 61 6c 6c 20 61 73 73 6f 63 69 61  ace call associa
1c220 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
1c230 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c240 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  n] D..**.** {H12
1c250 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  803} The [sqlite
1c260 33 5f 65 72 72 6d 73 67 28 44 29 5d 20 61 6e 64  3_errmsg(D)] and
1c270 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1c280 31 36 28 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  16(D)].**       
1c290 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65     interfaces re
1c2a0 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
1c2b0 67 75 61 67 65 20 74 65 78 74 20 74 68 61 74 20  guage text that 
1c2c0 64 65 73 63 72 69 62 65 73 0a 2a 2a 20 20 20 20  describes.**    
1c2d0 20 20 20 20 20 20 74 68 65 20 65 72 72 6f 72 20        the error 
1c2e0 69 6e 20 74 68 65 20 6d 6f 73 74 6c 79 20 72 65  in the mostly re
1c2f0 63 65 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e  cently failed in
1c300 74 65 72 66 61 63 65 20 63 61 6c 6c 2c 0a 2a 2a  terface call,.**
1c310 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 65            encode
1c320 64 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  d as either UTF-
1c330 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
1c340 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
1c350 7b 48 31 32 38 30 37 7d 20 54 68 65 20 73 74 72  {H12807} The str
1c360 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1c370 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1c380 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1c390 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20  _errmsg16()].** 
1c3a0 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61 6c           are val
1c3b0 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  id until the nex
1c3c0 74 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  t SQLite interfa
1c3d0 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b  ce call..**.** {
1c3e0 48 31 32 38 30 38 7d 20 43 61 6c 6c 73 20 74 6f  H12808} Calls to
1c3f0 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 74 68   API routines th
1c400 61 74 20 64 6f 20 6e 6f 74 20 72 65 74 75 72 6e  at do not return
1c410 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a   an error code.*
1c420 2a 20 20 20 20 20 20 20 20 20 20 28 65 78 61 6d  *          (exam
1c430 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  ple: [sqlite3_da
1c440 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f 20  ta_count()]) do 
1c450 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  not.**          
1c460 63 68 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72  change the error
1c470 20 63 6f 64 65 20 6f 72 20 6d 65 73 73 61 67 65   code or message
1c480 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1c490 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1c4a0 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73  3_errcode()], [s
1c4b0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1c4c0 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  , or [sqlite3_er
1c4d0 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  rmsg16()]..**.**
1c4e0 20 7b 48 31 32 38 30 39 7d 20 49 6e 74 65 72 66   {H12809} Interf
1c4f0 61 63 65 73 20 74 68 61 74 20 61 72 65 20 6e 6f  aces that are no
1c500 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
1c510 68 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  h a specific.** 
1c520 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
1c530 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
1c540 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20 20 20 20  examples:.**    
1c550 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d        [sqlite3_m
1c560 70 72 69 6e 74 66 28 29 5d 20 6f 72 20 5b 73 71  printf()] or [sq
1c570 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
1c580 72 65 64 5f 63 61 63 68 65 28 29 5d 0a 2a 2a 20  red_cache()].** 
1c590 20 20 20 20 20 20 20 20 20 64 6f 20 6e 6f 74 20           do not 
1c5a0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
1c5b0 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
1c5c0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1c5d0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b  e3_errcode()], [
1c5e0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1c5f0 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  ], or [sqlite3_e
1c600 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f 0a 69  rrmsg16()]..*/.i
1c610 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
1c620 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
1c630 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1c640 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
1c650 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
1c660 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
1c670 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  g16(sqlite3*);..
1c680 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c690 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
1c6a0 6a 65 63 74 20 7b 48 31 33 30 30 30 7d 20 3c 48  ject {H13000} <H
1c6b0 31 33 30 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  13010>.** KEYWOR
1c6c0 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
1c6d0 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
1c6e0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
1c6f0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
1c700 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
1c710 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
1c720 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
1c730 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
1c740 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b  t is variously k
1c750 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61  nown as a "prepa
1c760 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  red statement" o
1c770 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64  r a.** "compiled
1c780 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20   SQL statement" 
1c790 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22  or simply as a "
1c7a0 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a  statement"..**.*
1c7b0 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20  * The life of a 
1c7c0 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
1c7d0 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20   goes something 
1c7e0 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
1c7f0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
1c800 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20  eate the object 
1c810 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
1c820 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1c830 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20  a related.**    
1c840 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c    function..** <
1c850 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
1c860 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74  to [host paramet
1c870 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
1c880 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
1c890 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
1c8a0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
1c8b0 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
1c8c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
1c8d0 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
1c8e0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
1c8f0 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65  eset the stateme
1c900 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
1c910 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
1c920 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
1c930 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
1c940 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
1c950 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
1c960 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
1c970 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
1c980 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
1c990 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65  * </ol>.**.** Re
1c9a0 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61  fer to documenta
1c9b0 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
1c9c0 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  al methods above
1c9d0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
1c9e0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
1c9f0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
1ca00 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
1ca10 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
1ca20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
1ca30 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20 7b 48  n-time Limits {H
1ca40 31 32 37 36 30 7d 20 3c 53 32 30 36 30 30 3e 0a  12760} <S20600>.
1ca50 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
1ca60 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
1ca70 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
1ca80 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
1ca90 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
1caa0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
1cab0 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
1cac0 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
1cad0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
1cae0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1caf0 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
1cb00 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
1cb10 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
1cb20 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
1cb30 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
1cb40 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
1cb50 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
1cb60 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
1cb70 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
1cb80 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
1cb90 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
1cba0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
1cbb0 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
1cbc0 63 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20  construct.  The 
1cbd0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1cbe0 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a   the old limit..
1cbf0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65 77  **.** If the new
1cc00 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
1cc10 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
1cc20 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
1cc30 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20  ged..** For the 
1cc40 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 6f  limit category o
1cc50 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58  f SQLITE_LIMIT_X
1cc60 59 5a 20 74 68 65 72 65 20 69 73 20 61 20 68 61  YZ there is a ha
1cc70 72 64 20 75 70 70 65 72 0a 2a 2a 20 62 6f 75 6e  rd upper.** boun
1cc80 64 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69  d set by a compi
1cc90 6c 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f  le-time C prepro
1cca0 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d  cessor macro nam
1ccb0 65 64 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59  ed SQLITE_MAX_XY
1ccc0 5a 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  Z..** (The "_LIM
1ccd0 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
1cce0 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
1ccf0 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65  _MAX_".).** Atte
1cd00 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
1cd10 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
1cd20 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
1cd30 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
1cd40 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
1cd50 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
1cd60 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  limit..**.** Run
1cd70 20 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65   time limits are
1cd80 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
1cd90 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
1cda0 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
1cdb0 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
1cdc0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
1cdd0 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
1cde0 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
1cdf0 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
1ce00 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
1ce10 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
1ce20 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
1ce30 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
1ce40 20 77 65 62 62 72 6f 77 73 65 72 20 74 68 61 74   webbrowser that
1ce50 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
1ce60 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
1ce70 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
1ce80 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
1ce90 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
1cea0 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
1ceb0 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
1cec0 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
1ced0 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
1cee0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
1cef0 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
1cf00 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
1cf10 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
1cf20 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
1cf30 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
1cf40 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
1cf50 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
1cf60 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
1cf70 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
1cf80 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
1cf90 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
1cfa0 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
1cfb0 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
1cfc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1cfd0 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
1cfe0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
1cff0 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
1d000 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
1d010 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
1d020 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
1d030 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
1d040 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
1d050 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
1d060 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
1d070 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
1d080 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
1d090 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
1d0a0 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
1d0b0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
1d0c0 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  eases..**.** INV
1d0d0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1d0e0 48 31 32 37 36 32 7d 20 41 20 73 75 63 63 65 73  H12762} A succes
1d0f0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
1d100 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c  lite3_limit(D,C,
1d110 56 29 5d 20 77 68 65 72 65 20 56 20 69 73 0a 2a  V)] where V is.*
1d120 2a 20 20 20 20 20 20 20 20 20 20 70 6f 73 69 74  *          posit
1d130 69 76 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ive changes the 
1d140 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69 7a  limit on the siz
1d150 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20 43  e of construct C
1d160 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
1d170 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
1d180 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 74  nnection] D to t
1d190 68 65 20 6c 65 73 73 65 72 20 6f 66 20 56 20 61  he lesser of V a
1d1a0 6e 64 20 74 68 65 20 68 61 72 64 20 75 70 70 65  nd the hard uppe
1d1b0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6f  r.**          bo
1d1c0 75 6e 64 20 6f 6e 20 74 68 65 20 73 69 7a 65 20  und on the size 
1d1d0 6f 66 20 43 20 74 68 61 74 20 69 73 20 73 65 74  of C that is set
1d1e0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1d1f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 36 7d  ..**.** {H12766}
1d200 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
1d210 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c  ll to [sqlite3_l
1d220 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65  imit(D,C,V)] whe
1d230 72 65 20 56 20 69 73 20 6e 65 67 61 74 69 76 65  re V is negative
1d240 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c 65 61  .**          lea
1d250 76 65 73 20 74 68 65 20 73 74 61 74 65 20 6f 66  ves the state of
1d260 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1d270 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 75 6e 63  onnection] D unc
1d280 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  hanged..**.** {H
1d290 31 32 37 36 39 7d 20 41 20 73 75 63 63 65 73 73  12769} A success
1d2a0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
1d2b0 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56  ite3_limit(D,C,V
1d2c0 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  )] returns the.*
1d2d0 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
1d2e0 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e   of the limit on
1d2f0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e   the size of con
1d300 73 74 72 75 63 74 20 43 20 69 6e 20 74 68 65 0a  struct C in the.
1d310 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
1d320 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d330 5d 20 44 20 61 73 20 69 74 20 77 61 73 20 70 72  ] D as it was pr
1d340 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e  ior to the call.
1d350 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1d360 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
1d370 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
1d380 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
1d390 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
1d3a0 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 20  imit Categories 
1d3b0 7b 48 31 32 37 39 30 7d 20 3c 48 31 32 37 36 30  {H12790} <H12760
1d3c0 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
1d3d0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
1d3e0 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  {limit categorie
1d3f0 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
1d400 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
1d410 76 61 72 69 6f 75 73 20 61 73 70 65 63 74 73 20  various aspects 
1d420 6f 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  of a [database c
1d430 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68  onnection].** th
1d440 61 74 20 63 61 6e 20 62 65 20 6c 69 6d 69 74 65  at can be limite
1d450 64 20 69 6e 20 73 69 7a 65 20 62 79 20 63 61 6c  d in size by cal
1d460 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c  ls to [sqlite3_l
1d470 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
1d480 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
1d490 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 61  various limits a
1d4a0 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  re as follows:.*
1d4b0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
1d4c0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
1d4d0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1d4e0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
1d4f0 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
1d500 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
1d510 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20   row.<dd>.**.** 
1d520 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1d530 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
1d540 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1d550 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
1d560 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c   SQL statement.<
1d570 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1d580 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
1d590 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
1d5a0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1d5b0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
1d5c0 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
1d5d0 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
1d5e0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
1d5f0 53 45 4c 45 43 54 20 6f 72 20 74 68 65 20 6d 61  SELECT or the ma
1d600 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1d610 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
1d620 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
1d630 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
1d640 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
1d650 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1d660 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
1d670 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
1d680 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
1d690 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
1d6a0 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
1d6b0 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ssion.</dd>.**.*
1d6c0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1d6d0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
1d6e0 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
1d6f0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1d700 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
1d710 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
1d720 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a  statement.</dd>.
1d730 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1d740 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
1d750 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1d760 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1d770 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
1d780 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
1d790 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
1d7a0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
1d7b0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1d7c0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1d7d0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
1d7e0 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
1d7f0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1d800 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
1d810 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
1d820 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
1d830 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1d840 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
1d850 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1d860 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 74 74  um number of att
1d870 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 2e  ached databases.
1d880 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1d890 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
1d8a0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
1d8b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1d8c0 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
1d8d0 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
1d8e0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 4c  rgument to the L
1d8f0 49 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f 42 20 6f  IKE or.** GLOB o
1d900 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a  perators.</dd>.*
1d910 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1d920 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
1d930 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
1d940 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1d950 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65  mber of variable
1d960 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  s in an SQL stat
1d970 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a  ement that can.*
1d980 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e  * be bound.</dd>
1d990 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
1d9a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1d9b0 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  T_LENGTH        
1d9c0 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
1d9d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1d9e0 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20  IT_SQL_LENGTH   
1d9f0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
1da00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1da10 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20  MIT_COLUMN      
1da20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
1da30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1da40 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20  IMIT_EXPR_DEPTH 
1da50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
1da60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1da70 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
1da80 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
1da90 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
1daa0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20  _LIMIT_VDBE_OP  
1dab0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1dac0 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
1dad0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
1dae0 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20  _ARG            
1daf0 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
1db00 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
1db10 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
1db20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
1db30 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
1db40 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20  ATTERN_LENGTH   
1db50 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
1db60 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
1db70 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20  BLE_NUMBER      
1db80 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41       9../*.** CA
1db90 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e  PI3REF: Compilin
1dba0 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  g An SQL Stateme
1dbb0 6e 74 20 7b 48 31 33 30 31 30 7d 20 3c 53 31 30  nt {H13010} <S10
1dbc0 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  000>.** KEYWORDS
1dbd0 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  : {SQL statement
1dbe0 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a   compiler}.**.**
1dbf0 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53   To execute an S
1dc00 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73  QL query, it mus
1dc10 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
1dc20 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
1dc30 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
1dc40 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
1dc50 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
1dc60 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
1dc70 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20  ument, "db", is 
1dc80 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
1dc90 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64  ection] obtained
1dca0 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72   from a.** prior
1dcb0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1dcc0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1dcd0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
1dce0 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
1dcf0 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  6()]..**.** The 
1dd00 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
1dd10 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20   "zSql", is the 
1dd20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
1dd30 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
1dd40 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
1dd50 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
1dd60 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
1dd70 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
1dd80 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a  e3_prepare_v2().
1dd90 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
1dda0 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c  e UTF-8, and sql
1ddb0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1ddc0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1ddd0 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75  pare16_v2().** u
1dde0 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  se UTF-16..**.**
1ddf0 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72   If the nByte ar
1de00 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74  gument is less t
1de10 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a  han zero, then z
1de20 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
1de30 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a  o the.** first z
1de40 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1de50 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  If nByte is non-
1de60 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
1de70 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  t is the maximum
1de80 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62  .** number of  b
1de90 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
1dea0 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65  Sql.  When nByte
1deb0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
1dec0 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74  , the.** zSql st
1ded0 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74  ring ends at eit
1dee0 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c  her the first '\
1def0 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27  000' or '\u0000'
1df00 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a   character or.**
1df10 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79   the nByte-th by
1df20 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  te, whichever co
1df30 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68  mes first. If th
1df40 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a  e caller knows.*
1df50 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  * that the suppl
1df60 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
1df70 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
1df80 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  en there is a sm
1df90 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e  all.** performan
1dfa0 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
1dfb0 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73  be gained by pas
1dfc0 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
1dfd0 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
1dfe0 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  is equal to the 
1dff0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1e000 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
1e010 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
1e020 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
1e030 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73  terminator bytes
1e040 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20  ..**.** *pzTail 
1e050 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
1e060 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79   to the first by
1e070 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  te past the end 
1e080 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
1e090 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1e0a0 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f   zSql.  These ro
1e0b0 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d 70  utines only comp
1e0c0 69 6c 65 20 74 68 65 20 66 69 72 73 74 0a 2a 2a  ile the first.**
1e0d0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
1e0e0 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69  ql, so *pzTail i
1e0f0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
1e100 74 6f 20 77 68 61 74 20 72 65 6d 61 69 6e 73 0a  to what remains.
1e110 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a  ** uncompiled..*
1e120 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20 69 73 20  *.** *ppStmt is 
1e130 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
1e140 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
1e150 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e160 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
1e170 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
1e180 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1e190 20 20 49 66 20 74 68 65 72 65 20 69 73 20 61 6e    If there is an
1e1a0 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
1e1b0 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
1e1c0 4c 2e 20 20 49 66 20 74 68 65 20 69 6e 70 75 74  L.  If the input
1e1d0 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
1e1e0 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
1e1f0 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
1e200 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
1e210 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
1e220 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
1e230 55 4c 4c 2e 0a 2a 2a 20 7b 41 31 33 30 31 38 7d  ULL..** {A13018}
1e240 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
1e250 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
1e260 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
1e270 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
1e280 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1e290 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1e2a0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
1e2b0 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
1e2c0 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a  d with it..**.**
1e2d0 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51   On success, [SQ
1e2e0 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
1e2f0 72 6e 65 64 2c 20 6f 74 68 65 72 77 69 73 65 20  rned, otherwise 
1e300 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
1e310 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1e320 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
1e330 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
1e340 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1e350 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
1e360 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
1e370 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
1e380 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
1e390 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
1e3a0 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
1e3b0 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
1e3c0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
1e3d0 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
1e3e0 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
1e3f0 2a 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e  * In the "v2" in
1e400 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
1e410 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1e420 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
1e430 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
1e440 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
1e450 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
1e460 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
1e470 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
1e480 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
1e490 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
1e4a0 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
1e4b0 65 68 61 76 65 20 61 20 64 69 66 66 65 72 65 6e  ehave a differen
1e4c0 74 6c 79 20 69 6e 20 74 77 6f 20 77 61 79 73 3a  tly in two ways:
1e4d0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
1e4e0 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  li>.** If the da
1e4f0 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
1e500 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
1e510 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
1e520 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
1e530 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
1e540 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
1e550 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
1e560 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
1e570 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
1e580 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
1e590 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
1e5a0 69 6e 2e 20 20 49 66 20 74 68 65 20 73 63 68 65  in.  If the sche
1e5b0 6d 61 20 68 61 73 20 63 68 61 6e 67 65 64 20 69  ma has changed i
1e5c0 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68 61 74 20  n.** a way that 
1e5d0 6d 61 6b 65 73 20 74 68 65 20 73 74 61 74 65 6d  makes the statem
1e5e0 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61  ent no longer va
1e5f0 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  lid, [sqlite3_st
1e600 65 70 28 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c  ep()] will still
1e610 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
1e620 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20 42 75 74  TE_SCHEMA].  But
1e630 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c 65 67 61   unlike the lega
1e640 63 79 20 62 65 68 61 76 69 6f 72 2c 20 5b 53 51  cy behavior, [SQ
1e650 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a  LITE_SCHEMA] is.
1e660 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61 6c 20 65  ** now a fatal e
1e670 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b  rror.  Calling [
1e680 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1e690 76 32 28 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c  v2()] again will
1e6a0 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a   not make the.**
1e6b0 20 65 72 72 6f 72 20 67 6f 20 61 77 61 79 2e 20   error go away. 
1e6c0 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73 71 6c 69   Note: use [sqli
1e6d0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f  te3_errmsg()] to
1e6e0 20 66 69 6e 64 20 74 68 65 20 74 65 78 74 0a 2a   find the text.*
1e6f0 2a 20 6f 66 20 74 68 65 20 70 61 72 73 69 6e 67  * of the parsing
1e700 20 65 72 72 6f 72 20 74 68 61 74 20 72 65 73 75   error that resu
1e710 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54  lts in an [SQLIT
1e720 45 5f 53 43 48 45 4d 41 5d 20 72 65 74 75 72 6e  E_SCHEMA] return
1e730 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
1e740 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e   <li>.** When an
1e750 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
1e760 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1e770 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
1e780 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
1e790 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
1e7a0 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
1e7b0 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 54 68 65  ror codes].  The
1e7c0 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
1e7d0 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
1e7e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
1e7f0 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
1e800 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
1e810 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
1e820 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79 6f 75 20  code.** and you 
1e830 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
1e840 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
1e850 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
1e860 65 74 28 29 5d 20 69 6e 20 6f 72 64 65 72 0a 2a  et()] in order.*
1e870 2a 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  * to find the un
1e880 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
1e890 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
1e8a0 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
1e8b0 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
1e8c0 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
1e8d0 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
1e8e0 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
1e8f0 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
1e900 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
1e910 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  l>.**.** INVARIA
1e920 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30  NTS:.**.** {H130
1e930 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  11} The [sqlite3
1e940 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71 6c  _prepare(db,zSql
1e950 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  ,...)] and.**   
1e960 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1e970 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53  prepare_v2(db,zS
1e980 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ql,...)] interfa
1e990 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 74 68  ces interpret th
1e9a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 65  e.**          te
1e9b0 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71 6c  xt in their zSql
1e9c0 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 55 54   parameter as UT
1e9d0 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30  F-8..**.** {H130
1e9e0 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  12} The [sqlite3
1e9f0 5f 70 72 65 70 61 72 65 31 36 28 64 62 2c 7a 53  _prepare16(db,zS
1ea00 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20  ql,...)] and.** 
1ea10 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1ea20 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 64  3_prepare16_v2(d
1ea30 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74  b,zSql,...)] int
1ea40 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72 65  erfaces interpre
1ea50 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  t the.**        
1ea60 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72 20    text in their 
1ea70 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61  zSql parameter a
1ea80 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
1ea90 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1eaa0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 33  r..**.** {H13013
1eab0 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61  } If the nByte a
1eac0 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
1ead0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64  te3_prepare_v2(d
1eae0 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e  b,zSql,nByte,...
1eaf0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
1eb00 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  nd its variants 
1eb10 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
1eb20 6f 2c 20 74 68 65 20 53 51 4c 20 74 65 78 74 20  o, the SQL text 
1eb30 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  is.**          r
1eb40 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 20 69 73  ead from zSql is
1eb50 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 20   read up to the 
1eb60 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
1eb70 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  nator..**.** {H1
1eb80 33 30 31 34 7d 20 49 66 20 74 68 65 20 6e 42 79  3014} If the nBy
1eb90 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  te argument to [
1eba0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1ebb0 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65  v2(db,zSql,nByte
1ebc0 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
1ebd0 20 20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61     and its varia
1ebe0 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  nts is non-negat
1ebf0 69 76 65 2c 20 74 68 65 6e 20 61 74 20 6d 6f 73  ive, then at mos
1ec00 74 20 6e 42 79 74 65 73 20 62 79 74 65 73 20 6f  t nBytes bytes o
1ec10 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  f.**          SQ
1ec20 4c 20 74 65 78 74 20 69 73 20 72 65 61 64 20 66  L text is read f
1ec30 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20  rom zSql..**.** 
1ec40 7b 48 31 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c  {H13015} In [sql
1ec50 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1ec60 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61  db,zSql,N,P,pzTa
1ec70 69 6c 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  il)] and its var
1ec80 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  iants.**        
1ec90 20 20 69 66 20 74 68 65 20 7a 53 71 6c 20 69 6e    if the zSql in
1eca0 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
1ecb0 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
1ecc0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
1ecd0 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 70 7a            and pz
1ece0 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
1ecf0 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  , then *pzTail i
1ed00 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
1ed10 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  to the.**       
1ed20 20 20 20 66 69 72 73 74 20 62 79 74 65 20 70 61     first byte pa
1ed30 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
1ed40 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
1ed50 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a  ement in zSql..*
1ed60 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f 64 6f  *          <todo
1ed70 3e 57 68 61 74 20 64 6f 65 73 20 2a 70 7a 54 61  >What does *pzTa
1ed80 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69 66 20 74  il point to if t
1ed90 68 65 72 65 20 69 73 20 6f 6e 65 20 73 74 61 74  here is one stat
1eda0 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a  ement?</todo>.**
1edb0 0a 2a 2a 20 7b 48 31 33 30 31 36 7d 20 41 20 73  .** {H13016} A s
1edc0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
1edd0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
1ede0 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c  re_v2(db,zSql,N,
1edf0 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20  ppStmt,...)].** 
1ee00 20 20 20 20 20 20 20 20 20 6f 72 20 6f 6e 65 20           or one 
1ee10 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  of its variants 
1ee20 77 72 69 74 65 73 20 69 6e 74 6f 20 2a 70 70 53  writes into *ppS
1ee30 74 6d 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  tmt a pointer to
1ee40 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20   a new.**       
1ee50 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
1ee60 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69  tement] or a poi
1ee70 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 69 66 20  nter to NULL if 
1ee80 7a 53 71 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  zSql contains.**
1ee90 20 20 20 20 20 20 20 20 20 20 6e 6f 74 68 69 6e            nothin
1eea0 67 20 6f 74 68 65 72 20 74 68 61 6e 20 77 68 69  g other than whi
1eeb0 74 65 73 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65  tespace or comme
1eec0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30  nts..**.** {H130
1eed0 31 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  19} The [sqlite3
1eee0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
1eef0 6e 74 65 72 66 61 63 65 20 61 6e 64 20 69 74 73  nterface and its
1ef00 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e   variants return
1ef10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
1ef20 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61  LITE_OK] or an a
1ef30 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
1ef40 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69  r code] upon fai
1ef50 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  lure..**.** {H13
1ef60 30 32 31 7d 20 42 65 66 6f 72 65 20 5b 73 71 6c  021} Before [sql
1ef70 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c  ite3_prepare(db,
1ef80 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70 53 74 6d  zSql,nByte,ppStm
1ef90 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72 20 69 74  t,pzTail)] or it
1efa0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  s.**          va
1efb0 72 69 61 6e 74 73 20 72 65 74 75 72 6e 73 20 61  riants returns a
1efc0 6e 20 65 72 72 6f 72 20 28 61 6e 79 20 76 61 6c  n error (any val
1efd0 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
1efe0 51 4c 49 54 45 5f 4f 4b 5d 29 2c 0a 2a 2a 20 20  QLITE_OK]),.**  
1eff0 20 20 20 20 20 20 20 20 74 68 65 79 20 66 69 72          they fir
1f000 73 74 20 73 65 74 20 2a 70 70 53 74 6d 74 20 74  st set *ppStmt t
1f010 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
1f020 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
1f030 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1f040 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1f050 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1f060 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1f070 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1f080 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1f090 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
1f0a0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1f0b0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1f0c0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1f0d0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1f0e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1f0f0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1f100 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1f110 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1f120 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1f130 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1f140 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1f150 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
1f160 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1f170 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
1f180 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
1f190 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
1f1a0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
1f1b0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
1f1c0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
1f1d0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
1f1e0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1f1f0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1f200 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1f210 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1f220 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1f230 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1f240 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1f250 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1f260 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
1f270 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1f280 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1f290 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1f2a0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1f2b0 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
1f2c0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1f2d0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
1f2e0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1f2f0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
1f300 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
1f310 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
1f320 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1f330 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1f340 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1f350 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1f360 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1f370 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1f380 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1f390 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1f3a0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
1f3b0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1f3c0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1f3d0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1f3e0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
1f3f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1f400 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
1f410 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1f420 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1f430 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1f440 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1f450 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1f460 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
1f470 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1f480 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1f490 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1f4a0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1f4b0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1f4c0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1f4d0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1f4e0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1f4f0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
1f500 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1f510 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1f520 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1f530 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 52 45  );../*.** CAPIRE
1f540 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
1f550 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b 48 31 33  atement SQL {H13
1f560 31 30 30 7d 20 3c 48 31 33 30 30 30 3e 0a 2a 2a  100} <H13000>.**
1f570 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1f580 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
1f590 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76  o retrieve a sav
1f5a0 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f  ed copy of the o
1f5b0 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74  riginal.** SQL t
1f5c0 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
1f5d0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
1f5e0 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61  tatement] if tha
1f5f0 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a  t statement was.
1f600 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e  ** compiled usin
1f610 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
1f620 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1f630 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
1f640 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
1f650 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1f660 2a 0a 2a 2a 20 7b 48 31 33 31 30 31 7d 20 49 66  *.** {H13101} If
1f670 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1f680 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64  tatement] passed
1f690 20 61 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   as the argument
1f6a0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
1f6b0 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20  [sqlite3_sql()] 
1f6c0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  was compiled usi
1f6d0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
1f6e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1f6f0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
1f700 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f710 31 36 5f 76 32 28 29 5d 2c 20 74 68 65 6e 20 5b  16_v2()], then [
1f720 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 72  sqlite3_sql()] r
1f730 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
1f740 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20     a pointer to 
1f750 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1f760 64 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  d string contain
1f770 69 6e 67 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ing a UTF-8 rend
1f780 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  ering.**        
1f790 20 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61    of the origina
1f7a0 6c 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  l SQL statement.
1f7b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 32 7d 20  .**.** {H13102} 
1f7c0 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  If the [prepared
1f7d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 73   statement] pass
1f7e0 65 64 20 61 73 20 74 68 65 20 61 72 67 75 6d 65  ed as the argume
1f7f0 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  nt to.**        
1f800 20 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29    [sqlite3_sql()
1f810 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 75  ] was compiled u
1f820 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
1f830 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1f840 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
1f850 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1f860 36 28 29 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69  6()], then [sqli
1f870 74 65 33 5f 73 71 6c 28 29 5d 20 72 65 74 75 72  te3_sql()] retur
1f880 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
1f890 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 33  r..**.** {H13103
1f8a0 7d 20 54 68 65 20 73 74 72 69 6e 67 20 72 65 74  } The string ret
1f8b0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1f8c0 33 5f 73 71 6c 28 53 29 5d 20 69 73 20 76 61 6c  3_sql(S)] is val
1f8d0 69 64 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a 20  id until the.** 
1f8e0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
1f8f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
1f900 69 73 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67  is deleted using
1f910 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1f920 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  ze(S)]..*/.const
1f930 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1f940 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
1f950 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
1f960 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
1f970 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
1f980 65 20 4f 62 6a 65 63 74 20 7b 48 31 35 30 30 30  e Object {H15000
1f990 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45  } <S20200>.** KE
1f9a0 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
1f9b0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
1f9c0 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
1f9d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
1f9e0 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
1f9f0 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
1fa00 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
1fa10 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
1fa20 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
1fa30 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
1fa40 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
1fa50 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
1fa60 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
1fa70 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
1fa80 65 73 2e 20 56 61 6c 75 65 73 20 73 74 6f 72 65  es. Values store
1fa90 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
1faa0 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
1fab0 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
1fac0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
1fad0 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
1fae0 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
1faf0 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
1fb00 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
1fb10 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
1fb20 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
1fb30 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
1fb40 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
1fb50 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
1fb60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
1fb70 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
1fb80 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
1fb90 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
1fba0 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
1fbb0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1fbc0 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
1fbd0 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
1fbe0 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
1fbf0 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
1fc00 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
1fc10 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
1fc20 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
1fc30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
1fc40 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
1fc50 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
1fc60 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
1fc70 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
1fc80 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
1fc90 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65  is held.  A inte
1fca0 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
1fcb0 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
1fcc0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1fcd0 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
1fce0 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
1fcf0 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
1fd00 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1fd10 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
1fd20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
1fd30 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
1fd40 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
1fd50 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
1fd60 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
1fd70 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
1fd80 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
1fd90 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
1fda0 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
1fdb0 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
1fdc0 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
1fdd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
1fde0 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
1fdf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
1fe00 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
1fe10 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
1fe20 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
1fe30 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
1fe40 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
1fe50 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1fe60 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
1fe70 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
1fe80 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
1fe90 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
1fea0 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
1feb0 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
1fec0 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
1fed0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
1fee0 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
1fef0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 62  nction between b
1ff00 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
1ff10 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
1ff20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
1ff30 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
1ff40 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
1ff50 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
1ff60 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   The sqlite3_val
1ff70 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
1ff80 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
1ff90 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
1ffa0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
1ffb0 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
1ffc0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1ffd0 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
1ffe0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 54 68 65  rotected..** The
1fff0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
20000 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
20010 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
20020 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
20030 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a   unprotected..**
20040 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   Unprotected sql
20050 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
20060 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ts may only be u
20070 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  sed with.** [sql
20080 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
20090 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
200a0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e  3_bind_value()].
200b0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
200c0 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
200d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
200e0 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
200f0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
20100 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
20110 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
20120 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
20130 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
20140 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
20150 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46   CAPI3REF: SQL F
20160 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
20170 4f 62 6a 65 63 74 20 7b 48 31 36 30 30 31 7d 20  Object {H16001} 
20180 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20200>.**.** T
20190 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
201a0 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
201b0 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
201c0 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
201d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
201e0 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74  object.  A point
201f0 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
20200 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
20210 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
20220 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
20230 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
20240 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
20250 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
20260 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
20270 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
20280 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
20290 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
202a0 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
202b0 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
202c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
202d0 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
202e0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
202f0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
20300 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
20310 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
20320 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
20330 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
20340 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
20350 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
20360 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
20370 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
20380 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
20390 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
203a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
203b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
203c0 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
203d0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
203e0 6d 65 6e 74 73 20 7b 48 31 33 35 30 30 7d 20 3c  ments {H13500} <
203f0 53 37 30 33 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S70300>.** KEYWO
20400 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
20410 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
20420 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
20430 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
20440 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
20450 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
20460 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
20470 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
20480 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c  **.** In the SQL
20490 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74   strings input t
204a0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
204b0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
204c0 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
204d0 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
204e0 70 6c 61 63 65 64 20 62 79 20 61 20 70 61 72 61  placed by a para
204f0 6d 65 74 65 72 20 69 6e 20 6f 6e 65 20 6f 66 20  meter in one of 
20500 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a  these forms:.**.
20510 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
20520 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
20530 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
20540 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
20550 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
20560 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
20570 20 70 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73   parameter forms
20580 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e   shown above NNN
20590 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c   is an integer l
205a0 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56  iteral,.** and V
205b0 56 56 20 69 73 20 61 6e 20 61 6c 70 68 61 2d 6e  VV is an alpha-n
205c0 75 6d 65 72 69 63 20 70 61 72 61 6d 65 74 65 72  umeric parameter
205d0 20 6e 61 6d 65 2e 20 54 68 65 20 76 61 6c 75 65   name. The value
205e0 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
205f0 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
20600 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
20610 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
20620 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
20630 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
20640 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
20650 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
20660 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
20670 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
20680 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
20690 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
206a0 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
206b0 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
206c0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
206d0 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
206e0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
206f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20700 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
20710 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  ariants..**.** T
20720 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
20730 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
20740 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
20750 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
20760 2a 2a 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  ** The leftmost 
20770 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
20780 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
20790 20 20 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20    When the same 
207a0 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
207b0 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
207c0 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
207d0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
207e0 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
207f0 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
20800 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
20810 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
20820 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78 20 66 6f  .** The index fo
20830 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
20840 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
20850 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
20860 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
20870 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
20880 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
20890 2e 20 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20  .  The index.** 
208a0 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
208b0 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
208c0 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68  ue of NNN..** Th
208d0 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74  e NNN value must
208e0 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e   be between 1 an
208f0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  d the [sqlite3_l
20900 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d  imit()].** param
20910 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d  eter [SQLITE_LIM
20920 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
20930 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c  ER] (default val
20940 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20  ue: 999)..**.** 
20950 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
20960 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
20970 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
20980 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
20990 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
209a0 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
209b0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
209c0 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
209d0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
209e0 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
209f0 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
20a00 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
20a10 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
20a20 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
20a30 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
20a40 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
20a50 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66 20  aracters..** If 
20a60 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
20a70 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
20a80 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  , the length of 
20a90 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
20aa0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
20ab0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
20ac0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
20ad0 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ator..**.** The 
20ae0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
20af0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
20b00 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62  lob(), sqlite3_b
20b10 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a  ind_text(), and.
20b20 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
20b30 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65  text16() is a de
20b40 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
20b50 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
20b60 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e  BLOB or.** strin
20b70 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68  g after SQLite h
20b80 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
20b90 20 69 74 2e 20 49 66 20 74 68 65 20 66 69 66 74   it. If the fift
20ba0 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
20bb0 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
20bc0 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
20bd0 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
20be0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
20bf0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
20c00 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
20c10 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
20c20 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
20c30 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
20c40 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
20c50 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61  ument has the va
20c60 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  lue [SQLITE_TRAN
20c70 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20  SIENT], then.** 
20c80 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
20c90 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
20ca0 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d  y of the data im
20cb0 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
20cc0 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  e.** the sqlite3
20cd0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
20ce0 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  e returns..**.**
20cf0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   The sqlite3_bin
20d00 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
20d10 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
20d20 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
20d30 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
20d40 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 41 20  with zeroes.  A 
20d50 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
20d60 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
20d70 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
20d80 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
20d90 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
20da0 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
20db0 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
20dc0 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
20dd0 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
20de0 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
20df0 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
20e00 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
20e10 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
20e20 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
20e30 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
20e40 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
20e50 74 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67 61  tines..** A nega
20e60 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
20e70 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
20e80 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
20e90 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
20ea0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   The sqlite3_bin
20eb0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d  d_*() routines m
20ec0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66  ust be called af
20ed0 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ter.** [sqlite3_
20ee0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61  prepare_v2()] (a
20ef0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  nd its variants)
20f00 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
20f10 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66  et()] and.** bef
20f20 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ore [sqlite3_ste
20f30 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67  p()]..** Binding
20f40 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
20f50 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
20f60 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
20f70 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70  ne..** Unbound p
20f80 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
20f90 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
20fa0 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  L..**.** These r
20fb0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
20fc0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
20fd0 63 63 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f  ccess or an erro
20fe0 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79  r code if.** any
20ff0 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
21000 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  .  [SQLITE_RANGE
21010 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
21020 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
21030 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
21040 66 20 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54  f range.  [SQLIT
21050 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
21060 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
21070 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49   fails..** [SQLI
21080 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74  TE_MISUSE] might
21090 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20   be returned if 
210a0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
210b0 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a  re called on a.*
210c0 2a 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  * virtual machin
210d0 65 20 74 68 61 74 20 69 73 20 74 68 65 20 77 72  e that is the wr
210e0 6f 6e 67 20 73 74 61 74 65 20 6f 72 20 77 68 69  ong state or whi
210f0 63 68 20 68 61 73 20 61 6c 72 65 61 64 79 20 62  ch has already b
21100 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a  een finalized..*
21110 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d  * Detection of m
21120 69 73 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61  isuse is unrelia
21130 62 6c 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ble.  Applicatio
21140 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65  ns should not de
21150 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54  pend.** on SQLIT
21160 45 5f 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73  E_MISUSE returns
21170 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  .  SQLITE_MISUSE
21180 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
21190 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20  indicate a.** a 
211a0 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74  logic error in t
211b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
211c0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
211d0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
211e0 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72  .** panic rather
211f0 20 74 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c   than return SQL
21200 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a  ITE_MISUSE..**.*
21210 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
21220 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
21230 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
21240 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
21250 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
21260 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
21270 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
21280 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  dex()]..**.** IN
21290 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
212a0 7b 48 31 33 35 30 36 7d 20 54 68 65 20 5b 53 51  {H13506} The [SQ
212b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
212c0 69 6c 65 72 5d 20 72 65 63 6f 67 6e 69 7a 65 73  iler] recognizes
212d0 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20 66   tokens of the f
212e0 6f 72 6d 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  orms.**         
212f0 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24   "?", "?NNN", "$
21300 56 56 56 22 2c 20 22 3a 56 56 56 22 2c 20 61 6e  VVV", ":VVV", an
21310 64 20 22 40 56 56 56 22 20 61 73 20 53 51 4c 20  d "@VVV" as SQL 
21320 70 61 72 61 6d 65 74 65 72 73 2c 0a 2a 2a 20 20  parameters,.**  
21330 20 20 20 20 20 20 20 20 77 68 65 72 65 20 4e 4e          where NN
21340 4e 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63  N is any sequenc
21350 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  e of one or more
21360 20 64 69 67 69 74 73 0a 2a 2a 20 20 20 20 20 20   digits.**      
21370 20 20 20 20 61 6e 64 20 77 68 65 72 65 20 56 56      and where VV
21380 56 20 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63  V is any sequenc
21390 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  e of one or more
213a0 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 0a 2a 2a   alphanumeric.**
213b0 20 20 20 20 20 20 20 20 20 20 63 68 61 72 61 63            charac
213c0 74 65 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70 74  ters or "::" opt
213d0 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64  ionally followed
213e0 20 62 79 20 61 20 73 74 72 69 6e 67 20 63 6f 6e   by a string con
213f0 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20  taining.**      
21400 20 20 20 20 6e 6f 20 73 70 61 63 65 73 20 61 6e      no spaces an
21410 64 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68  d contained with
21420 69 6e 20 70 61 72 65 6e 74 68 65 73 65 73 2e 0a  in parentheses..
21430 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 39 7d 20 54  **.** {H13509} T
21440 68 65 20 69 6e 69 74 69 61 6c 20 76 61 6c 75 65  he initial value
21450 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
21460 65 74 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  eter is NULL..**
21470 0a 2a 2a 20 7b 48 31 33 35 31 32 7d 20 54 68 65  .** {H13512} The
21480 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 22   index of an "?"
21490 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
214a0 73 20 6f 6e 65 20 6c 61 72 67 65 72 20 74 68 61  s one larger tha
214b0 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
214c0 20 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20    largest index 
214d0 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  of SQL parameter
214e0 20 74 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f 72   to the left, or
214f0 20 31 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20   1 if.**        
21500 20 20 74 68 65 20 22 3f 22 20 69 73 20 74 68 65    the "?" is the
21510 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
21520 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
21530 48 31 33 35 31 35 7d 20 54 68 65 20 69 6e 64 65  H13515} The inde
21540 78 20 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22 20 53  x of an "?NNN" S
21550 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
21560 74 68 65 20 69 6e 74 65 67 65 72 20 4e 4e 4e 2e  the integer NNN.
21570 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 38 7d 20  .**.** {H13518} 
21580 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  The index of an 
21590 22 3a 56 56 56 22 2c 20 22 24 56 56 56 22 2c 20  ":VVV", "$VVV", 
215a0 6f 72 20 22 40 56 56 56 22 20 53 51 4c 20 70 61  or "@VVV" SQL pa
215b0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20  rameter is.**   
215c0 20 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20         the same 
215d0 61 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  as the index of 
215e0 6c 65 66 74 6d 6f 73 74 20 6f 63 63 75 72 72 65  leftmost occurre
215f0 6e 63 65 73 20 6f 66 20 74 68 65 20 73 61 6d 65  nces of the same
21600 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
21610 61 6d 65 74 65 72 2c 20 6f 72 20 6f 6e 65 20 6d  ameter, or one m
21620 6f 72 65 20 74 68 61 6e 20 74 68 65 20 6c 61 72  ore than the lar
21630 67 65 73 74 20 69 6e 64 65 78 20 6f 76 65 72 20  gest index over 
21640 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
21650 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
21660 65 20 6c 65 66 74 20 69 66 20 74 68 69 73 20 69  e left if this i
21670 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
21680 72 72 65 6e 63 65 0a 2a 2a 20 20 20 20 20 20 20  rrence.**       
21690 20 20 20 6f 66 20 74 68 69 73 20 70 61 72 61 6d     of this param
216a0 65 74 65 72 2c 20 6f 72 20 31 20 69 66 20 74 68  eter, or 1 if th
216b0 69 73 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f  is is the leftmo
216c0 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
216d0 0a 2a 2a 20 7b 48 31 33 35 32 31 7d 20 54 68 65  .** {H13521} The
216e0 20 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   [SQL statement 
216f0 63 6f 6d 70 69 6c 65 72 5d 20 66 61 69 6c 73 20  compiler] fails 
21700 77 69 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f  with an [SQLITE_
21710 52 41 4e 47 45 5d 0a 2a 2a 20 20 20 20 20 20 20  RANGE].**       
21720 20 20 20 65 72 72 6f 72 20 69 66 20 74 68 65 20     error if the 
21730 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
21740 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
21750 73 20 74 68 61 6e 20 31 0a 2a 2a 20 20 20 20 20  s than 1.**     
21760 20 20 20 20 20 6f 72 20 67 72 65 61 74 65 72 20       or greater 
21770 74 68 61 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  than the compile
21780 2d 74 69 6d 65 20 53 51 4c 49 54 45 5f 4d 41 58  -time SQLITE_MAX
21790 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
217a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72  .**          par
217b0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ameter..**.** {H
217c0 31 33 35 32 34 7d 20 43 61 6c 6c 73 20 74 6f 20  13524} Calls to 
217d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
217e0 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  xt | sqlite3_bin
217f0 64 28 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a  d(S,N,V,...)].**
21800 20 20 20 20 20 20 20 20 20 20 61 73 73 6f 63 69            associ
21810 61 74 65 20 74 68 65 20 76 61 6c 75 65 20 56 20  ate the value V 
21820 77 69 74 68 20 61 6c 6c 20 53 51 4c 20 70 61 72  with all SQL par
21830 61 6d 65 74 65 72 73 20 68 61 76 69 6e 67 20 61  ameters having a
21840 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  n.**          in
21850 64 65 78 20 6f 66 20 4e 20 69 6e 20 74 68 65 20  dex of N in the 
21860 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21870 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ent] S..**.** {H
21880 31 33 35 32 37 7d 20 43 61 6c 6c 73 20 74 6f 20  13527} Calls to 
21890 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
218a0 78 74 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  xt | sqlite3_bin
218b0 64 28 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  d(S,N,...)].**  
218c0 20 20 20 20 20 20 20 20 6f 76 65 72 72 69 64 65          override
218d0 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74   prior calls wit
218e0 68 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  h the same value
218f0 73 20 6f 66 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a  s of S and N..**
21900 0a 2a 2a 20 7b 48 31 33 35 33 30 7d 20 42 69 6e  .** {H13530} Bin
21910 64 69 6e 67 73 20 65 73 74 61 62 6c 69 73 68 65  dings establishe
21920 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 69  d by [sqlite3_bi
21930 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
21940 33 5f 62 69 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a  3_bind(S,...)].*
21950 2a 20 20 20 20 20 20 20 20 20 20 70 65 72 73 69  *          persi
21960 73 74 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20  st across calls 
21970 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
21980 74 28 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  t(S)]..**.** {H1
21990 33 35 33 33 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3533} In calls t
219a0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
219b0 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  blob(S,N,V,L,D)]
219c0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
219d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
219e0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72  (S,N,V,L,D)], or
219f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
21a00 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
21a10 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51  6(S,N,V,L,D)] SQ
21a20 4c 69 74 65 20 62 69 6e 64 73 20 74 68 65 20 66  Lite binds the f
21a30 69 72 73 74 20 4c 0a 2a 2a 20 20 20 20 20 20 20  irst L.**       
21a40 20 20 20 62 79 74 65 73 20 6f 66 20 74 68 65 20     bytes of the 
21a50 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 70  BLOB or string p
21a60 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2c 20  ointed to by V, 
21a70 77 68 65 6e 20 4c 0a 2a 2a 20 20 20 20 20 20 20  when L.**       
21a80 20 20 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69     is non-negati
21a90 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33  ve..**.** {H1353
21aa0 36 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  6} In calls to [
21ab0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
21ac0 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72  t(S,N,V,L,D)] or
21ad0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
21ae0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
21af0 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51  6(S,N,V,L,D)] SQ
21b00 4c 69 74 65 20 62 69 6e 64 73 20 63 68 61 72 61  Lite binds chara
21b10 63 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  cters.**        
21b20 20 20 66 72 6f 6d 20 56 20 74 68 72 6f 75 67 68    from V through
21b30 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
21b40 63 68 61 72 61 63 74 65 72 20 77 68 65 6e 20 4c  character when L
21b50 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a   is negative..**
21b60 0a 2a 2a 20 7b 48 31 33 35 33 39 7d 20 49 6e 20  .** {H13539} In 
21b70 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
21b80 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c  3_bind_blob(S,N,
21b90 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,L,D)],.**     
21ba0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
21bb0 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c  nd_text(S,N,V,L,
21bc0 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
21bd0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
21be0 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
21bf0 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74  ,D)] when D is t
21c00 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20  he special.**   
21c10 20 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20         constant 
21c20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
21c30 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
21c40 74 68 61 74 20 74 68 65 20 76 61 6c 75 65 20 56  that the value V
21c50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
21c60 68 65 6c 64 20 69 6e 20 73 74 61 74 69 63 20 75  held in static u
21c70 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 74  nmanaged space t
21c80 68 61 74 20 77 69 6c 6c 20 6e 6f 74 20 63 68 61  hat will not cha
21c90 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nge.**          
21ca0 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
21cb0 69 6d 65 20 6f 66 20 74 68 65 20 62 69 6e 64 69  ime of the bindi
21cc0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34  ng..**.** {H1354
21cd0 32 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b  2} In calls to [
21ce0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
21cf0 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a  b(S,N,V,L,D)],.*
21d00 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
21d10 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c  te3_bind_text(S,
21d20 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  N,V,L,D)], or.**
21d30 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
21d40 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53  e3_bind_text16(S
21d50 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20  ,N,V,L,D)] when 
21d60 44 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  D is the special
21d70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
21d80 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 54 52  stant [SQLITE_TR
21d90 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 20 72 6f  ANSIENT], the ro
21da0 75 74 69 6e 65 20 6d 61 6b 65 73 20 61 0a 2a 2a  utine makes a.**
21db0 20 20 20 20 20 20 20 20 20 20 70 72 69 76 61 74            privat
21dc0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 61  e copy of the va
21dd0 6c 75 65 20 56 20 62 65 66 6f 72 65 20 69 74 20  lue V before it 
21de0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b  returns..**.** {
21df0 48 31 33 35 34 35 7d 20 49 6e 20 63 61 6c 6c 73  H13545} In calls
21e00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
21e10 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44  d_blob(S,N,V,L,D
21e20 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
21e30 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
21e40 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20  xt(S,N,V,L,D)], 
21e50 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
21e60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
21e70 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20  t16(S,N,V,L,D)] 
21e80 77 68 65 6e 20 44 20 69 73 20 61 20 70 6f 69 6e  when D is a poin
21e90 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ter to.**       
21ea0 20 20 20 61 20 66 75 6e 63 74 69 6f 6e 2c 20 53     a function, S
21eb0 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
21ec0 61 74 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 64  at function to d
21ed0 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20 20 20  estroy the.**   
21ee0 20 20 20 20 20 20 20 76 61 6c 75 65 20 56 20 61         value V a
21ef0 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
21f00 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20 76  shed using the v
21f10 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48  alue V..**.** {H
21f20 31 33 35 34 38 7d 20 49 6e 20 63 61 6c 6c 73 20  13548} In calls 
21f30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
21f40 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  _zeroblob(S,N,V,
21f50 4c 29 5d 20 74 68 65 20 76 61 6c 75 65 20 62 6f  L)] the value bo
21f60 75 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  und.**          
21f70 69 73 20 61 20 42 4c 4f 42 20 6f 66 20 4c 20 62  is a BLOB of L b
21f80 79 74 65 73 2c 20 6f 72 20 61 20 7a 65 72 6f 2d  ytes, or a zero-
21f90 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 66 20 4c  length BLOB if L
21fa0 20 69 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a   is negative..**
21fb0 0a 2a 2a 20 7b 48 31 33 35 35 31 7d 20 49 6e 20  .** {H13551} In 
21fc0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
21fd0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 53 2c 4e  3_bind_value(S,N
21fe0 2c 56 29 5d 20 74 68 65 20 56 20 61 72 67 75 6d  ,V)] the V argum
21ff0 65 6e 74 20 6d 61 79 0a 2a 2a 20 20 20 20 20 20  ent may.**      
22000 20 20 20 20 62 65 20 65 69 74 68 65 72 20 61 20      be either a 
22010 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
22020 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
22030 20 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20   or an.**       
22040 20 20 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20     [unprotected 
22050 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
22060 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  bject..*/.int sq
22070 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
22080 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
22090 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
220a0 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
220b0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
220c0 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
220d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
220e0 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e  int, double);.in
220f0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
22100 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
22110 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74  , int, int);.int
22120 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
22130 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
22140 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
22150 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69  int64);.int sqli
22160 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
22170 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
22180 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
22190 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
221a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
221b0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c  st char*, int n,
221c0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
221d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
221e0 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
221f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
22200 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
22210 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
22220 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
22230 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
22240 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
22250 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
22260 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
22270 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
22280 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
22290 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
222a0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
222b0 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
222c0 72 73 20 7b 48 31 33 36 30 30 7d 20 3c 53 37 30  rs {H13600} <S70
222d0 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  300>.**.** This 
222e0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
222f0 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20  sed to find the 
22300 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70  number of [SQL p
22310 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e  arameters].** in
22320 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
22330 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61  tement].  SQL pa
22340 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b  rameters are tok
22350 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f  ens of the.** fo
22360 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20  rm "?", "?NNN", 
22370 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20  ":AAA", "$AAA", 
22380 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73  or "@AAA" that s
22390 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65  erve as.** place
223a0 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75  holders for valu
223b0 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c  es that are [sql
223c0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
223d0 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68   bound].** to th
223e0 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20  e parameters at 
223f0 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a  a later time..**
22400 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
22410 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e   actually return
22420 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
22430 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68  he largest (righ
22440 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65  tmost).** parame
22450 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72  ter. For all for
22460 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20  ms except ?NNN, 
22470 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73  this will corres
22480 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e  pond to the.** n
22490 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20  umber of unique 
224a0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20  parameters.  If 
224b0 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
224c0 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c  e ?NNN are used,
224d0 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
224e0 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
224f0 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  t..**.** See als
22500 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
22510 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
22520 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
22530 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
22540 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
22550 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
22560 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
22570 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
22580 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
22590 36 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  601} The [sqlite
225a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
225b0 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72  _count(S)] inter
225c0 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
225d0 20 20 20 20 20 20 20 20 20 74 68 65 20 6c 61 72           the lar
225e0 67 65 73 74 20 69 6e 64 65 78 20 6f 66 20 61 6c  gest index of al
225f0 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  l SQL parameters
22600 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
22610 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
22620 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30  atement] S, or 0
22630 20 69 66 20 53 20 63 6f 6e 74 61 69 6e 73 20 6e   if S contains n
22640 6f 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  o SQL parameters
22650 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
22660 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
22670 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
22680 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
22690 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
226a0 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20   Host Parameter 
226b0 7b 48 31 33 36 32 30 7d 20 3c 53 37 30 33 30 30  {H13620} <S70300
226c0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  >.**.** This rou
226d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
226e0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61  ointer to the na
226f0 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a  me of the n-th.*
22700 2a 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  * [SQL parameter
22710 5d 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] in a [prepared
22720 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
22730 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
22740 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
22750 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
22760 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
22770 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
22780 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
22790 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
227a0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
227b0 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
227c0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
227d0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
227e0 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
227f0 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
22800 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
22810 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
22820 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65  ame..** Paramete
22830 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
22840 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
22850 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
22860 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
22870 6e 64 20 61 72 65 20 61 6c 73 6f 20 72 65 66 65  nd are also refe
22880 72 72 65 64 20 74 6f 20 61 73 20 22 61 6e 6f 6e  rred to as "anon
22890 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
228a0 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  "..**.** The fir
228b0 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
228c0 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
228d0 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
228e0 2a 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e  * If the value n
228f0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
22900 20 6f 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20   or if the n-th 
22910 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
22920 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
22930 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
22940 20 20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73    The returned s
22950 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61  tring is.** alwa
22960 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f  ys in UTF-8 enco
22970 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ding even if the
22980 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
22990 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   was.** original
229a0 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ly specified as 
229b0 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74  UTF-16 in [sqlit
229c0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
229d0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  or.** [sqlite3_p
229e0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
229f0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
22a00 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
22a10 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
22a20 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
22a30 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
22a40 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
22a50 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
22a60 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
22a70 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
22a80 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 32  TS:.**.** {H1362
22a90 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
22aa0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
22ab0 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ame(S,N)] interf
22ac0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
22ad0 20 20 20 20 20 20 20 20 61 20 55 54 46 2d 38 20          a UTF-8 
22ae0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
22af0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
22b00 20 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a   parameter in.**
22b10 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70            the [p
22b20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22b30 74 5d 20 53 20 68 61 76 69 6e 67 20 69 6e 64 65  t] S having inde
22b40 78 20 4e 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  x N, or.**      
22b50 20 20 20 20 4e 55 4c 4c 20 69 66 20 74 68 65 72      NULL if ther
22b60 65 20 69 73 20 6e 6f 20 53 51 4c 20 70 61 72 61  e is no SQL para
22b70 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64 65 78  meter with index
22b80 20 4e 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20   N or if the.** 
22b90 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74           paramet
22ba0 65 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20  er with index N 
22bb0 69 73 20 61 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20  is an anonymous 
22bc0 70 61 72 61 6d 65 74 65 72 20 22 3f 22 2e 0a 2a  parameter "?"..*
22bd0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
22be0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
22bf0 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
22c00 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
22c10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22c20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
22c30 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
22c40 6e 20 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d 20  n Name {H13640} 
22c50 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52  <S70300>.**.** R
22c60 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
22c70 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
22c80 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
22c90 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65  me.  The.** inde
22ca0 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
22cb0 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
22cc0 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
22cd0 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
22ce0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
22cf0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
22d00 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a  nd()].  A zero.*
22d10 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
22d20 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
22d30 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
22d40 20 20 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a    The parameter.
22d50 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
22d60 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
22d70 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
22d80 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
22d90 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
22da0 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
22db0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
22dc0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
22dd0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
22de0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
22df0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
22e00 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
22e10 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
22e20 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
22e30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
22e40 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
22e50 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
22e60 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 34 31  S:.**.** {H13641
22e70 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
22e80 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
22e90 64 65 78 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  dex(S,N)] interf
22ea0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ace returns.**  
22eb0 20 20 20 20 20 20 20 20 74 68 65 20 69 6e 64 65          the inde
22ec0 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74  x of SQL paramet
22ed0 65 72 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  er in the [prepa
22ee0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
22ef0 2a 20 20 20 20 20 20 20 20 20 20 53 20 77 68 6f  *          S who
22f00 73 65 20 6e 61 6d 65 20 6d 61 74 63 68 65 73 20  se name matches 
22f10 74 68 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67  the UTF-8 string
22f20 20 4e 2c 20 6f 72 20 30 20 69 66 20 74 68 65 72   N, or 0 if ther
22f30 65 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  e is.**         
22f40 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e   no match..*/.in
22f50 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
22f60 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
22f70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
22f80 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
22f90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22fa0 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
22fb0 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
22fc0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 48  red Statement {H
22fd0 31 33 36 36 30 7d 20 3c 53 37 30 33 30 30 3e 0a  13660} <S70300>.
22fe0 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74  **.** Contrary t
22ff0 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
23000 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
23010 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
23020 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
23030 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
23040 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
23050 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
23060 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 55 73  tatement]..** Us
23070 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
23080 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
23090 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
230a0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ULL..**.** INVAR
230b0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
230c0 33 36 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3661} The [sqlit
230d0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
230e0 73 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  s(S)] interface 
230f0 72 65 73 65 74 73 20 61 6c 6c 20 53 51 4c 0a 2a  resets all SQL.*
23100 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
23110 65 74 65 72 20 62 69 6e 64 69 6e 67 73 20 69 6e  eter bindings in
23120 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
23130 74 61 74 65 6d 65 6e 74 5d 20 53 20 62 61 63 6b  tatement] S back
23140 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
23150 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
23160 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
23170 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
23180 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
23190 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
231a0 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37  Result Set {H137
231b0 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  10} <S10700>.**.
231c0 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75  ** Return the nu
231d0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
231e0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
231f0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  t returned by th
23200 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
23210 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20  tatement]. This 
23220 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
23230 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e  0 if pStmt is an
23240 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
23250 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  t that does not 
23260 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72  return data (for
23270 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
23280 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ATE])..**.** INV
23290 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
232a0 48 31 33 37 31 31 7d 20 54 68 65 20 5b 73 71 6c  H13711} The [sql
232b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
232c0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
232d0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
232e0 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  er of.**        
232f0 20 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65    columns in the
23300 20 72 65 73 75 6c 74 20 73 65 74 20 67 65 6e 65   result set gene
23310 72 61 74 65 64 20 62 79 20 74 68 65 20 5b 70 72  rated by the [pr
23320 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23330 5d 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] S,.**         
23340 20 6f 72 20 30 20 69 66 20 53 20 64 6f 65 73 20   or 0 if S does 
23350 6e 6f 74 20 67 65 6e 65 72 61 74 65 20 61 20 72  not generate a r
23360 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e  esult set..*/.in
23370 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
23380 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
23390 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
233a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
233b0 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
233c0 52 65 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37  Result Set {H137
233d0 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  20} <S10700>.**.
233e0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
233f0 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
23400 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
23410 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
23420 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
23430 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
23440 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
23450 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   The sqlite3_col
23460 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
23470 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
23480 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
23490 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
234a0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
234b0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
234c0 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
234d0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
234e0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
234f0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
23500 6e 67 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ng.  The first p
23510 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
23520 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23530 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
23540 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
23550 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
23560 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
23570 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
23580 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54  olumn number.  T
23590 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
235a0 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
235b0 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  **.** The return
235c0 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
235d0 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
235e0 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
235f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23600 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
23610 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
23620 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
23630 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
23640 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
23650 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73  lumn_name() or s
23660 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
23670 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61  me16() on the sa
23680 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
23690 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   If sqlite3_mall
236a0 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
236b0 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
236c0 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
236d0 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
236e0 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
236f0 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
23700 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
23710 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
23720 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
23730 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  .**.** The name 
23740 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
23750 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
23760 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
23770 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
23780 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
23790 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
237a0 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
237b0 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
237c0 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
237d0 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
237e0 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
237f0 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
23800 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
23810 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
23820 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  t..**.** INVARIA
23830 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  NTS:.**.** {H137
23840 32 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  21} A successful
23850 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
23860 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
23870 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a  mn_name(S,N)].**
23880 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
23890 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
238a0 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 74 68 20  name of the Nth 
238b0 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20  column (where 0 
238c0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  is.**          t
238d0 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
238e0 6d 6e 29 20 66 6f 72 20 74 68 65 20 72 65 73 75  mn) for the resu
238f0 6c 74 20 73 65 74 20 6f 66 20 74 68 65 0a 2a 2a  lt set of the.**
23900 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
23910 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
23920 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   as a zero-termi
23930 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
23940 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32  ng..**.** {H1372
23950 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  3} A successful 
23960 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
23970 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
23980 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 0a 2a  n_name16(S,N)].*
23990 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
239a0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
239b0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 74 68   name of the Nth
239c0 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20 30   column (where 0
239d0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
239e0 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  the leftmost col
239f0 75 6d 6e 29 20 66 6f 72 20 74 68 65 20 72 65 73  umn) for the res
23a00 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 0a 2a  ult set of the.*
23a10 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
23a20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
23a30 53 20 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  S as a zero-term
23a40 69 6e 61 74 65 64 20 55 54 46 2d 31 36 20 73 74  inated UTF-16 st
23a50 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ring.**         
23a60 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
23a70 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a  yte order..**.**
23a80 20 7b 48 31 33 37 32 34 7d 20 54 68 65 20 5b 73   {H13724} The [s
23a90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
23aa0 6d 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  me()] and [sqlit
23ab0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
23ac0 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
23ad0 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72  interfaces retur
23ae0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
23af0 20 69 66 20 74 68 65 79 20 61 72 65 20 75 6e 61   if they are una
23b00 62 6c 65 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ble to.**       
23b10 20 20 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f     allocate memo
23b20 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 69 72  ry to hold their
23b30 20 6e 6f 72 6d 61 6c 20 72 65 74 75 72 6e 20 73   normal return s
23b40 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  trings..**.** {H
23b50 31 33 37 32 35 7d 20 49 66 20 74 68 65 20 4e 20  13725} If the N 
23b60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
23b70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
23b80 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20  e(S,N)] or.**   
23b90 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
23ba0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c  column_name16(S,
23bb0 4e 29 5d 20 69 73 20 6f 75 74 20 6f 66 20 72 61  N)] is out of ra
23bc0 6e 67 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  nge, then the.**
23bd0 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
23be0 61 63 65 73 20 72 65 74 75 72 6e 20 61 20 4e 55  aces return a NU
23bf0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
23c00 2a 20 7b 48 31 33 37 32 36 7d 20 54 68 65 20 73  * {H13726} The s
23c10 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
23c20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
23c30 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 61 6e  mn_name(S,N)] an
23c40 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
23c50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
23c60 6d 65 31 36 28 53 2c 4e 29 5d 20 61 72 65 20 76  me16(S,N)] are v
23c70 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e  alid until the n
23c80 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ext.**          
23c90 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 72  call to either r
23ca0 6f 75 74 69 6e 65 20 77 69 74 68 20 74 68 65 20  outine with the 
23cb0 73 61 6d 65 20 53 20 61 6e 64 20 4e 20 70 61 72  same S and N par
23cc0 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20  ameters.**      
23cd0 20 20 20 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71      or until [sq
23ce0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
23cf0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2a  )] is called..**
23d00 0a 2a 2a 20 7b 48 31 33 37 32 37 7d 20 57 68 65  .** {H13727} Whe
23d10 6e 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  n a result colum
23d20 6e 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  n of a [SELECT] 
23d30 73 74 61 74 65 6d 65 6e 74 20 63 6f 6e 74 61 69  statement contai
23d40 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ns.**          a
23d50 6e 20 41 53 20 63 6c 61 75 73 65 2c 20 74 68 65  n AS clause, the
23d60 20 6e 61 6d 65 20 6f 66 20 74 68 61 74 20 63 6f   name of that co
23d70 6c 75 6d 6e 20 69 73 20 74 68 65 20 69 64 65 6e  lumn is the iden
23d80 74 69 66 69 65 72 0a 2a 2a 20 20 20 20 20 20 20  tifier.**       
23d90 20 20 20 74 6f 20 74 68 65 20 72 69 67 68 74 20     to the right 
23da0 6f 66 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72  of the AS keywor
23db0 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  d..*/.const char
23dc0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
23dd0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
23de0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
23df0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
23e00 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
23e10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23e20 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
23e30 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
23e40 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
23e50 20 52 65 73 75 6c 74 20 7b 48 31 33 37 34 30 7d   Result {H13740}
23e60 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10700>.**.** 
23e70 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
23e80 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
23e90 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74  o determine what
23ea0 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a   column of what.
23eb0 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63  ** table in whic
23ec0 68 20 64 61 74 61 62 61 73 65 20 61 20 72 65 73  h database a res
23ed0 75 6c 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  ult of a [SELECT
23ee0 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65  ] statement come
23ef0 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e  s from..** The n
23f00 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
23f10 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
23f20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
23f30 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
23f40 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
23f50 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54  TF-16 string.  T
23f60 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
23f70 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
23f80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
23f90 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
23fa0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
23fb0 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
23fc0 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
23fd0 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
23fe0 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
23ff0 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  me..** The retur
24000 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
24010 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
24020 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24030 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
24040 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
24050 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
24060 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
24070 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
24080 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
24090 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
240a0 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
240b0 20 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72   The names retur
240c0 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
240d0 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
240e0 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
240f0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
24100 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
24110 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
24120 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c  ument to the fol
24130 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20  lowing calls is 
24140 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
24150 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65  ement]..** These
24160 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
24170 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
24180 6f 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  out the Nth colu
24190 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
241a0 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
241b0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
241c0 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
241d0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
241e0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
241f0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
24200 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
24210 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
24220 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
24230 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
24240 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
24250 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
24260 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
24270 4c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  L.  These routin
24280 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
24290 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
242a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
242b0 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
242c0 20 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65    Otherwise, the
242d0 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  y return the nam
242e0 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
242f0 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
24300 65 0a 2a 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  e.** and column 
24310 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
24320 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  t column was ext
24330 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
24340 2a 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  ** As with all o
24350 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
24360 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65  , those postfixe
24370 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
24380 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
24390 6f 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68  oded strings, th
243a0 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
243b0 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 20  s return UTF-8. 
243c0 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  {END}.**.** Thes
243d0 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
243e0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
243f0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
24400 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
24410 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
24420 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
24430 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
24440 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
24450 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 0a  .**.** {A13751}.
24460 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
24470 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
24480 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
24490 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
244a0 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
244b0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
244c0 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
244d0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
244e0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
244f0 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
24500 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
24510 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  NTS:.**.** {H137
24520 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  41} The [sqlite3
24530 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
24540 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65  _name(S,N)] inte
24550 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69  rface returns ei
24560 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
24570 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d   the UTF-8 zero-
24580 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
24590 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
245a0 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a  from which the.*
245b0 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
245c0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
245d0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
245e0 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78  atement] S is ex
245f0 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20  tracted,.**     
24600 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20       or NULL if 
24610 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
24620 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c  f S is a general
24630 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20   expression.**  
24640 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e          or if un
24650 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
24660 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65   memory to store
24670 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a   the name..**.**
24680 20 7b 48 31 33 37 34 32 7d 20 54 68 65 20 5b 73   {H13742} The [s
24690 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
246a0 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 53 2c  tabase_name16(S,
246b0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
246c0 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
246d0 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46           the UTF
246e0 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
246f0 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69  order zero-termi
24700 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68  nated name of th
24710 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20  e database.**   
24720 20 20 20 20 20 20 20 66 72 6f 6d 20 77 68 69 63         from whic
24730 68 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  h the Nth result
24740 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b   column of the [
24750 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24760 6e 74 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20 20  nt] S is.**     
24770 20 20 20 20 20 65 78 74 72 61 63 74 65 64 2c 20       extracted, 
24780 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e  or NULL if the N
24790 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
247a0 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72  s a general expr
247b0 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ession.**       
247c0 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20     or if unable 
247d0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
247e0 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20  ry to store the 
247f0 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  name..**.** {H13
24800 37 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  743} The [sqlite
24810 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
24820 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ame(S,N)] interf
24830 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
24840 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
24850 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  he UTF-8 zero-te
24860 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
24870 20 74 68 65 20 74 61 62 6c 65 20 66 72 6f 6d 20   the table from 
24880 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20  which the.**    
24890 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74        Nth result
248a0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b   column of the [
248b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
248c0 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74  nt] S is extract
248d0 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ed,.**          
248e0 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e  or NULL if the N
248f0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
24900 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72  s a general expr
24910 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ession.**       
24920 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20     or if unable 
24930 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
24940 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20  ry to store the 
24950 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  name..**.** {H13
24960 37 34 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  744} The [sqlite
24970 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
24980 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65  ame16(S,N)] inte
24990 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69  rface returns ei
249a0 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ther.**         
249b0 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69   the UTF-16 nati
249c0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65  ve byte order ze
249d0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
249e0 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  me of the table.
249f0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d  **          from
24a00 20 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 72   which the Nth r
24a10 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
24a20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
24a30 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a  atement] S is.**
24a40 20 20 20 20 20 20 20 20 20 20 65 78 74 72 61 63            extrac
24a50 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20  ted, or NULL if 
24a60 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
24a70 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c  f S is a general
24a80 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20   expression.**  
24a90 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e          or if un
24aa0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
24ab0 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65   memory to store
24ac0 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a   the name..**.**
24ad0 20 7b 48 31 33 37 34 35 7d 20 54 68 65 20 5b 73   {H13745} The [s
24ae0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
24af0 69 67 69 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20  igin_name(S,N)] 
24b00 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
24b10 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  s either.**     
24b20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a       the UTF-8 z
24b30 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
24b40 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ame of the table
24b50 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69   column from whi
24b60 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ch the.**       
24b70 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f     Nth result co
24b80 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65  lumn of the [pre
24b90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24ba0 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64 2c   S is extracted,
24bb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
24bc0 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20  NULL if the Nth 
24bd0 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61  column of S is a
24be0 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73   general express
24bf0 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
24c00 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
24c10 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
24c20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d  to store the nam
24c30 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 36  e..**.** {H13746
24c40 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
24c50 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
24c60 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  e16(S,N)] interf
24c70 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
24c80 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
24c90 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  he UTF-16 native
24ca0 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f   byte order zero
24cb0 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65  -terminated name
24cc0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
24cd0 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e            column
24ce0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
24cf0 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
24d00 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  n of the.**     
24d10 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
24d20 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65  tatement] S is e
24d30 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c  xtracted, or NUL
24d40 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  L if the Nth col
24d50 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  umn.**          
24d60 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61  of S is a genera
24d70 6c 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  l expression or 
24d80 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  if unable to all
24d90 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ocate memory.** 
24da0 20 20 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72           to stor
24db0 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a  e the name..**.*
24dc0 2a 20 7b 48 31 33 37 34 38 7d 20 54 68 65 20 72  * {H13748} The r
24dd0 65 74 75 72 6e 20 76 61 6c 75 65 73 20 66 72 6f  eturn values fro
24de0 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  m.**          [s
24df0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
24e00 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
24e10 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
24e20 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20  terfaces].**    
24e30 20 20 20 20 20 20 61 72 65 20 76 61 6c 69 64 20        are valid 
24e40 66 6f 72 20 74 68 65 20 6c 69 66 65 74 69 6d 65  for the lifetime
24e50 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
24e60 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
24e70 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69           or unti
24e80 6c 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69  l the encoding i
24e90 73 20 63 68 61 6e 67 65 64 20 62 79 20 61 6e 6f  s changed by ano
24ea0 74 68 65 72 20 6d 65 74 61 64 61 74 61 0a 2a 2a  ther metadata.**
24eb0 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
24ec0 61 63 65 20 63 61 6c 6c 20 66 6f 72 20 74 68 65  ace call for the
24ed0 20 73 61 6d 65 20 70 72 65 70 61 72 65 64 20 73   same prepared s
24ee0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
24ef0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  umn..**.** ASSUM
24f00 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
24f10 31 33 37 35 31 7d 20 49 66 20 74 77 6f 20 6f 72  13751} If two or
24f20 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
24f30 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
24f40 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
24f50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
24f60 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
24f70 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
24f80 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20  faces].**       
24f90 20 20 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20     for the same 
24fa0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24fb0 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
24fc0 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20  column.**       
24fd0 20 20 20 61 74 20 74 68 65 20 73 61 6d 65 20 74     at the same t
24fe0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
24ff0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
25000 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ed..*/.const cha
25010 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
25020 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
25030 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
25040 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
25050 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
25060 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
25070 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
25080 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
25090 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
250a0 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
250b0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
250c0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
250d0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
250e0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
250f0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
25100 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
25110 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
25120 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
25130 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
25140 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
25150 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
25160 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
25170 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25180 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
25190 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
251a0 65 73 75 6c 74 20 7b 48 31 33 37 36 30 7d 20 3c  esult {H13760} <
251b0 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S10700>.**.** Th
251c0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
251d0 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
251e0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
251f0 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
25200 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
25210 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
25220 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
25230 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
25240 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
25250 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
25260 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
25270 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
25280 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
25290 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
252a0 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
252b0 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
252c0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20  s returned.  If 
252d0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
252e0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
252f0 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
25300 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
25310 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
25320 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
25330 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e  d..** The return
25340 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
25350 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
25360 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46  d. {END}.**.** F
25370 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
25380 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
25390 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
253a0 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
253b0 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
253c0 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
253d0 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
253e0 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
253f0 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
25400 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
25410 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
25420 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
25430 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
25440 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
25450 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
25460 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
25470 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
25480 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
25490 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
254a0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
254b0 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
254c0 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20  ime typing.  So 
254d0 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
254e0 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
254f0 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
25500 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
25510 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
25520 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
25530 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
25540 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
25550 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
25560 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
25570 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
25580 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
25590 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
255a0 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20  ic.  Type.** is 
255b0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
255c0 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
255d0 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
255e0 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
255f0 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
25600 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49   values..**.** I
25610 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
25620 20 7b 48 31 33 37 36 31 7d 20 20 41 20 73 75 63   {H13761}  A suc
25630 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
25640 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
25650 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20 72  decltype(S,N)] r
25660 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20  eturns a.**     
25670 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69        zero-termi
25680 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
25690 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
256a0 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74  e declared datat
256b0 79 70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ype.**          
256c0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f   of the table co
256d0 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72  lumn that appear
256e0 73 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c  s as the Nth col
256f0 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 0a 2a 2a  umn (numbered.**
25700 20 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20             from 
25710 30 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  0) of the result
25720 20 73 65 74 20 74 6f 20 74 68 65 20 5b 70 72 65   set to the [pre
25730 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25740 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36   S..**.** {H1376
25750 32 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 6c  2}  A successful
25760 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
25770 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
25780 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20  e16(S,N)].**    
25790 20 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61         returns a
257a0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
257b0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
257c0 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67  yte order string
257d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f  .**           co
257e0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63  ntaining the dec
257f0 6c 61 72 65 64 20 64 61 74 61 74 79 70 65 20 6f  lared datatype o
25800 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
25810 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72 73 0a  mn that appears.
25820 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 20  **           as 
25830 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28  the Nth column (
25840 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d 20 30 29  numbered from 0)
25850 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
25860 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  et to the.**    
25870 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
25880 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
25890 2a 0a 2a 2a 20 7b 48 31 33 37 36 33 7d 20 20 49  *.** {H13763}  I
258a0 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
258b0 20 30 20 6f 72 20 4e 20 69 73 20 67 72 65 61 74   0 or N is great
258c0 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  er than or equal
258d0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
258e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
258f0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 5b 70  olumns in the [p
25900 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25910 74 5d 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20  t] S,.**        
25920 20 20 20 6f 72 20 69 66 20 74 68 65 20 4e 74 68     or if the Nth
25930 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
25940 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
25950 20 73 75 62 71 75 65 72 79 20 72 61 74 68 65 72   subquery rather
25960 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
25970 61 6e 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  an a table colum
25980 6e 2c 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72  n, or if a memor
25990 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
259a0 6c 75 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  lure.**         
259b0 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20    occurs during 
259c0 65 6e 63 6f 64 69 6e 67 20 63 6f 6e 76 65 72 73  encoding convers
259d0 69 6f 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  ions, then.**   
259e0 20 20 20 20 20 20 20 20 63 61 6c 6c 73 20 74 6f          calls to
259f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
25a00 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20  _decltype(S,N)] 
25a10 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
25a20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
25a30 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d  decltype16(S,N)]
25a40 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f   return NULL..*/
25a50 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
25a60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
25a70 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
25a80 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
25a90 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
25aa0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
25ab0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
25ac0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
25ad0 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20  EF: Evaluate An 
25ae0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48  SQL Statement {H
25af0 31 33 32 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a  13200} <S10000>.
25b00 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
25b10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25b20 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
25b30 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
25b40 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
25b50 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
25b60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
25b70 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
25b80 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
25b90 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
25ba0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
25bb0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
25bc0 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
25bd0 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
25be0 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
25bf0 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
25c00 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
25c10 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
25c20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
25c30 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
25c40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
25c50 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
25c60 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
25c70 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
25c80 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
25c90 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
25ca0 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
25cb0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
25cc0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
25cd0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
25ce0 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
25cf0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
25d00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
25d10 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
25d20 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
25d30 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
25d40 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
25d50 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
25d60 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
25d70 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
25d80 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
25d90 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
25da0 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
25db0 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  d..**.** In the 
25dc0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
25dd0 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
25de0 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
25df0 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
25e00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
25e10 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
25e20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
25e30 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
25e40 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65  SE]..** With the
25e50 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
25e60 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
25e70 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
25e80 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
25e90 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
25ea0 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
25eb0 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
25ec0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
25ed0 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
25ee0 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
25ef0 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
25f00 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
25f10 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
25f20 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
25f30 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
25f40 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
25f50 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
25f60 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
25f70 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
25f80 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
25f90 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
25fa0 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
25fb0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
25fc0 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
25fd0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a  ccurs within a.*
25fe0 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
25ff0 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
26000 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
26010 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
26020 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
26030 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  uing..**.** [SQL
26040 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
26050 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
26060 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
26070 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
26080 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
26090 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
260a0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
260b0 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
260c0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
260d0 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
260e0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
260f0 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
26100 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
26110 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
26120 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
26130 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  te..**.** If the
26140 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
26150 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
26160 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
26170 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  then [SQLITE_ROW
26180 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
26190 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77   each time a new
261a0 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20   row of data is 
261b0 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73  ready for proces
261c0 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63  sing by the.** c
261d0 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65  aller. The value
261e0 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  s may be accesse
261f0 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c  d using the [col
26200 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
26210 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
26220 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
26230 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
26240 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
26250 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
26260 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
26270 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
26280 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
26290 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
262a0 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
262b0 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
262c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
262d0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
262e0 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
262f0 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
26300 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
26310 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
26320 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
26330 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20  )]..** With the 
26340 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
26350 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
26360 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
26370 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
26380 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
26390 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
263a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
263b0 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
263c0 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
263d0 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
263e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
263f0 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
26400 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26410 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22 20  ].  In the "v2" 
26420 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
26430 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
26440 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
26450 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
26460 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
26470 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
26480 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
26490 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
264a0 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
264b0 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
264c0 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
264d0 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
264e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
264f0 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
26500 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
26510 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
26520 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
26530 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
26540 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
26550 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
26560 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
26570 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
26580 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
26590 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
265a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
265b0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
265c0 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
265d0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
265e0 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
265f0 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c  in time..**.** <
26600 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
26610 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
26620 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
26630 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
26640 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
26650 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
26660 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
26670 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
26680 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
26690 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
266a0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
266b0 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
266c0 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
266d0 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
266e0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
266f0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
26700 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
26710 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
26720 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
26730 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
26740 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
26750 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
26760 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
26770 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
26780 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
26790 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
267a0 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
267b0 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
267c0 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
267d0 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
267e0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
267f0 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
26800 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
26810 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
26820 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
26830 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
26840 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
26850 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
26860 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
26870 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
26880 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
26890 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
268a0 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
268b0 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
268c0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
268d0 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
268e0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
268f0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
26900 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
26910 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 32 30  TS:.**.** {H1320
26920 32 7d 20 20 49 66 20 74 68 65 20 5b 70 72 65 70  2}  If the [prep
26930 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
26940 53 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65  S is ready to be
26950 20 72 75 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20   run, then.**   
26960 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
26970 5f 73 74 65 70 28 53 29 5d 20 61 64 76 61 6e 63  _step(S)] advanc
26980 65 73 20 74 68 61 74 20 70 72 65 70 61 72 65 64  es that prepared
26990 20 73 74 61 74 65 6d 65 6e 74 20 75 6e 74 69 6c   statement until
269a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f  .**           co
269b0 6d 70 6c 65 74 69 6f 6e 20 6f 72 20 75 6e 74 69  mpletion or unti
269c0 6c 20 69 74 20 69 73 20 72 65 61 64 79 20 74 6f  l it is ready to
269d0 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 20   return another 
269e0 72 6f 77 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  row of the.**   
269f0 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73          result s
26a00 65 74 2c 20 6f 72 20 75 6e 74 69 6c 20 61 6e 20  et, or until an 
26a10 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
26a20 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 0a  pt | interrupt].
26a30 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 20  **           or 
26a40 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
26a50 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b   occurs..**.** {
26a60 48 31 35 33 30 34 7d 20 20 57 68 65 6e 20 61 20  H15304}  When a 
26a70 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
26a80 5f 73 74 65 70 28 53 29 5d 20 63 61 75 73 65 73  _step(S)] causes
26a90 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
26aa0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20  tatement].**    
26ab0 20 20 20 20 20 20 20 53 20 74 6f 20 72 75 6e 20         S to run 
26ac0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c 20 74  to completion, t
26ad0 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
26ae0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  rns [SQLITE_DONE
26af0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 36  ]..**.** {H15306
26b00 7d 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74  }  When a call t
26b10 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
26b20 53 29 5d 20 73 74 6f 70 73 20 62 65 63 61 75 73  S)] stops becaus
26b30 65 20 69 74 20 69 73 20 72 65 61 64 79 20 74 6f  e it is ready to
26b40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
26b50 74 75 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77  turn another row
26b60 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
26b70 65 74 2c 20 69 74 20 72 65 74 75 72 6e 73 20 5b  et, it returns [
26b80 53 51 4c 49 54 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a  SQLITE_ROW]..**.
26b90 2a 2a 20 7b 48 31 35 33 30 38 7d 20 20 49 66 20  ** {H15308}  If 
26ba0 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
26bb0 65 33 5f 73 74 65 70 28 53 29 5d 20 65 6e 63 6f  e3_step(S)] enco
26bc0 75 6e 74 65 72 73 20 61 6e 0a 2a 2a 20 20 20 20  unters an.**    
26bd0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
26be0 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65  interrupt | inte
26bf0 72 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d  rrupt] or a run-
26c00 74 69 6d 65 20 65 72 72 6f 72 2c 0a 2a 2a 20 20  time error,.**  
26c10 20 20 20 20 20 20 20 20 20 69 74 20 72 65 74 75           it retu
26c20 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
26c30 74 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 68  te error code th
26c40 61 74 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  at is not one of
26c50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53  .**           [S
26c60 51 4c 49 54 45 5f 4f 4b 5d 2c 20 5b 53 51 4c 49  QLITE_OK], [SQLI
26c70 54 45 5f 52 4f 57 5d 2c 20 6f 72 20 5b 53 51 4c  TE_ROW], or [SQL
26c80 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a  ITE_DONE]..**.**
26c90 20 7b 48 31 35 33 31 30 7d 20 20 49 66 20 61 6e   {H15310}  If an
26ca0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
26cb0 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d  upt | interrupt]
26cc0 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65   or a run-time e
26cd0 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rror.**         
26ce0 20 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20    occurs during 
26cf0 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
26d00 65 33 5f 73 74 65 70 28 53 29 5d 0a 2a 2a 20 20  e3_step(S)].**  
26d10 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20 5b           for a [
26d20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26d30 6e 74 5d 20 53 20 63 72 65 61 74 65 64 20 75 73  nt] S created us
26d40 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
26d50 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
26d60 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
26d70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  are()] or.**    
26d80 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
26d90 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
26da0 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
26db0 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a  returns either.*
26dc0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  *           [SQL
26dd0 49 54 45 5f 45 52 52 4f 52 5d 2c 20 5b 53 51 4c  ITE_ERROR], [SQL
26de0 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72 20 5b 53  ITE_BUSY], or [S
26df0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a  QLITE_MISUSE]..*
26e00 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
26e10 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
26e20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26e30 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
26e40 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
26e50 74 20 73 65 74 20 7b 48 31 33 37 37 30 7d 20 3c  t set {H13770} <
26e60 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65  S10700>.**.** Re
26e70 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
26e80 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68   of values in th
26e90 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
26ea0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e   the result set.
26eb0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
26ec0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 37 31  S:.**.** {H13771
26ed0 7d 20 20 41 66 74 65 72 20 61 20 63 61 6c 6c 20  }  After a call 
26ee0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
26ef0 28 53 29 5d 20 74 68 61 74 20 72 65 74 75 72 6e  (S)] that return
26f00 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 0a  s [SQLITE_ROW],.
26f10 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65  **           the
26f20 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
26f30 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e 65  ount(S)] routine
26f40 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65   will return the
26f50 20 73 61 6d 65 20 76 61 6c 75 65 0a 2a 2a 20 20   same value.**  
26f60 20 20 20 20 20 20 20 20 20 61 73 20 74 68 65 20           as the 
26f70 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
26f80 63 6f 75 6e 74 28 53 29 5d 20 66 75 6e 63 74 69  count(S)] functi
26f90 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 37  on..**.** {H1377
26fa0 32 7d 20 20 41 66 74 65 72 20 5b 73 71 6c 69 74  2}  After [sqlit
26fb0 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
26fc0 72 65 74 75 72 6e 65 64 20 61 6e 79 20 76 61 6c  returned any val
26fd0 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a  ue other than.**
26fe0 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49             [SQLI
26ff0 54 45 5f 52 4f 57 5d 20 6f 72 20 62 65 66 6f 72  TE_ROW] or befor
27000 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
27010 53 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  S)] has been cal
27020 6c 65 64 20 6f 6e 20 74 68 65 0a 2a 2a 20 20 20  led on the.**   
27030 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
27040 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f 72  d statement] for
27050 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
27060 73 69 6e 63 65 20 69 74 20 77 61 73 0a 2a 2a 20  since it was.** 
27070 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
27080 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
27090 70 61 72 65 64 5d 20 6f 72 20 5b 73 71 6c 69 74  pared] or [sqlit
270a0 65 33 5f 72 65 73 65 74 20 7c 20 72 65 73 65 74  e3_reset | reset
270b0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ],.**           
270c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  the [sqlite3_dat
270d0 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74  a_count(S)] rout
270e0 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ine returns zero
270f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
27100 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
27110 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
27120 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27130 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
27140 61 74 61 74 79 70 65 73 20 7b 48 31 30 32 36 35  atatypes {H10265
27150 7d 20 3c 53 31 30 31 31 30 3e 3c 53 31 30 31 32  } <S10110><S1012
27160 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
27170 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
27180 2a 20 7b 48 31 30 32 36 36 7d 20 45 76 65 72 79  * {H10266} Every
27190 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
271a0 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
271b0 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
271c0 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
271d0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
271e0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
271f0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
27200 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
27210 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
27220 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
27230 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
27240 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e  ULL.** </ul> {EN
27250 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  D}.**.** These c
27260 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
27270 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
27280 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
27290 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
272a0 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
272b0 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
272c0 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
272d0 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
272e0 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
272f0 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
27300 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
27310 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
27320 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
27330 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
27340 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
27350 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
27360 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
27370 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
27380 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
27390 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
273a0 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
273b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
273c0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
273d0 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
273e0 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
273f0 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
27400 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
27410 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
27420 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
27430 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
27440 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
27450 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
27460 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
27470 20 51 75 65 72 79 20 7b 48 31 33 38 30 30 7d 20   Query {H13800} 
27480 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S10700>.** KEYW
27490 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
274a0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
274b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
274c0 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72  ines form the "r
274d0 65 73 75 6c 74 20 73 65 74 20 71 75 65 72 79 22  esult set query"
274e0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
274f0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
27500 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
27510 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
27520 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
27530 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
27540 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
27550 79 2e 20 20 49 6e 20 65 76 65 72 79 20 63 61 73  y.  In every cas
27560 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
27570 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
27580 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
27590 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
275a0 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
275b0 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
275c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
275d0 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
275e0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
275f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
27600 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
27610 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
27620 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
27630 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
27640 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
27650 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
27660 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
27670 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c  returned.  The l
27680 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
27690 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
276a0 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
276b0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
276c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
276d0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
276e0 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
276f0 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
27700 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
27710 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
27720 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
27730 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
27740 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
27750 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
27760 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
27770 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
27780 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
27790 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
277a0 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
277b0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
277c0 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
277d0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
277e0 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
277f0 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
27800 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
27810 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
27820 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
27830 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
27840 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
27850 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
27860 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
27870 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
27880 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
27890 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
278a0 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
278b0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
278c0 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
278d0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
278e0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
278f0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
27900 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
27910 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
27920 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
27930 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
27940 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
27950 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
27960 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
27970 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
27980 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   The sqlite3_col
27990 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
279a0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
279b0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
279c0 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
279d0 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
279e0 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
279f0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
27a00 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72  lumn.  The retur
27a10 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
27a20 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
27a30 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
27a40 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
27a50 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
27a60 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
27a70 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
27a80 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
27a90 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
27aa0 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
27ab0 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
27ac0 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
27ad0 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
27ae0 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
27af0 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
27b00 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
27b10 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
27b20 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
27b30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
27b40 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
27b50 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
27b60 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
27b70 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
27b80 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
27b90 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
27ba0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
27bb0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
27bc0 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
27bd0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
27be0 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
27bf0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
27c00 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
27c10 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
27c20 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
27c30 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
27c40 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66  or string..** If
27c50 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
27c60 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
27c70 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
27c80 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
27c90 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
27ca0 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
27cb0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
27cc0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
27cd0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  ..** If the resu
27ce0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
27cf0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
27d00 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
27d10 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
27d20 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
27d30 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
27d40 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
27d50 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
27d60 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
27d70 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
27d80 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65  t string..** The
27d90 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
27da0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
27db0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
27dc0 61 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a  ator at the end.
27dd0 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
27de0 2e 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20  .  For clarity: 
27df0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
27e00 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ed is the number
27e10 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
27e20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
27e30 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
27e40 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
27e50 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
27e60 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
27e70 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
27e80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
27e90 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65  t16(),.** even e
27ea0 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72  mpty strings, ar
27eb0 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65  e always zero te
27ec0 72 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 72  rminated.  The r
27ed0 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
27ee0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
27ef0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
27f00 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
27f10 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
27f20 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73  .** pointer, pos
27f30 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c  sibly even a NUL
27f40 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
27f50 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   The sqlite3_col
27f60 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f  umn_bytes16() ro
27f70 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
27f80 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
27f90 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75  mn_bytes().** bu
27fa0 74 20 6c 65 61 76 65 73 20 74 68 65 20 72 65 73  t leaves the res
27fb0 75 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e  ult in UTF-16 in
27fc0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
27fd0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54  er instead of UT
27fe0 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 72 6f  F-8..** The zero
27ff0 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e   terminator is n
28000 6f 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ot included in t
28010 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a  his count..**.**
28020 20 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75   The object retu
28030 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
28040 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
28050 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
28060 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
28070 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41  alue] object.  A
28080 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
28090 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
280a0 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ct.** may only b
280b0 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c  e used with [sql
280c0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
280d0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
280e0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
280f0 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
28100 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28110 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
28120 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
28130 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
28140 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
28150 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
28160 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
28170 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
28180 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  ike [sqlite3_val
28190 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
281a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
281b0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
281c0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
281d0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
281e0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
281f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
28200 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74  utines attempt t
28210 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
28220 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70  lue where approp
28230 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  riate.  For.** e
28240 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
28250 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
28260 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
28270 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
28280 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
28290 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
282a0 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
282b0 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
282c0 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
282d0 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
282e0 63 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c  cally.  The foll
282f0 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
28300 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
28310 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ons.** that are 
28320 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
28330 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
28340 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
28350 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
28360 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
28370 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
28380 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
28390 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
283a0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
283b0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
283c0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
283d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
283e0 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
283f0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
28400 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
28410 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
28420 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
28430 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
28440 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
28450 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
28460 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
28470 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
28480 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
28490 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
284a0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
284b0 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
284c0 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
284d0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
284e0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
284f0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
28500 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
28510 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
28520 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
28530 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
28540 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54  me as INTEGER->T
28550 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
28560 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
28570 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
28580 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20  vert from float 
28590 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  to integer.** <t
285a0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
285b0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
285c0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
285d0 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
285e0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
285f0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
28600 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
28610 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a  s FLOAT->TEXT.**
28620 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
28630 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
28640 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28    <td> Use atoi(
28650 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
28660 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
28670 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61  AT    <td> Use a
28680 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
28690 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
286a0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
286b0 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
286c0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
286d0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
286e0 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
286f0 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28  T then use atoi(
28700 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
28710 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  LOB    <td>  FLO
28720 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
28730 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
28740 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  use atof().** <t
28750 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
28760 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
28770 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
28780 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
28790 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
287a0 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
287b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
287c0 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66   above makes ref
287d0 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61  erence to standa
287e0 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e  rd C library fun
287f0 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a  ctions atoi().**
28800 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51   and atof().  SQ
28810 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65  Lite does not re
28820 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66  ally use these f
28830 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61  unctions.  It ha
28840 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75  s its.** own equ
28850 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c  ivalent internal
28860 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20   routines.  The 
28870 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28  atoi() and atof(
28880 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75  ) names are.** u
28890 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65  sed in the table
288a0 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64   for brevity and
288b0 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72   because they ar
288c0 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f  e familiar to mo
288d0 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d  st.** C programm
288e0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ers..**.** Note 
288f0 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
28900 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
28910 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
28920 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
28930 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
28940 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
28950 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
28960 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
28970 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28980 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
28990 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20  invalidated..** 
289a0 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
289b0 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
289c0 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
289d0 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
289e0 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
289f0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
28a00 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
28a10 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c   content is a BL
28a20 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  OB and sqlite3_c
28a30 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a  olumn_text() or.
28a40 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
28a50 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
28a60 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65  is called.  A ze
28a70 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69  ro-terminator mi
28a80 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64  ght.**      need
28a90 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20   to be added to 
28aa0 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e  the string.</li>
28ab0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
28ac0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
28ad0 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
28ae0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
28af0 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
28b00 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
28b10 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
28b20 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
28b30 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
28b40 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
28b50 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20  UTF-16.</li>.** 
28b60 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
28b70 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
28b80 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  16 text and sqli
28b90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28ba0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
28bb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
28bc0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
28bd0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
28be0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
28bf0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
28c00 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
28c10 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20  .** Conversions 
28c20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
28c30 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
28c40 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
28c50 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
28c60 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
28c70 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
28c80 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
28c90 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
28ca0 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
28cb0 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
28cc0 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20  inter points to 
28cd0 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
28ce0 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
28cf0 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
28d00 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
28d10 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
28d20 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
28d30 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
28d40 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
28d50 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
28d60 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
28d70 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
28d80 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
28d90 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73  e safest and eas
28da0 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72  iest to remember
28db0 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
28dc0 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
28dd0 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
28de0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
28df0 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
28e00 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
28e10 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
28e20 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
28e30 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
28e40 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
28e50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
28e60 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
28e70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
28e80 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
28e90 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
28ea0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
28eb0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
28ec0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
28ed0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
28ee0 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
28ef0 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
28f00 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
28f10 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
28f20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
28f30 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
28f40 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
28f50 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
28f60 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
28f70 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
28f80 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
28f90 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
28fa0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
28fb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
28fc0 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
28fd0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
28fe0 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
28ff0 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
29000 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29010 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
29020 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
29030 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
29040 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29050 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
29060 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
29070 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
29080 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
29090 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
290a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
290b0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  ()..**.** The po
290c0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
290d0 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
290e0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
290f0 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
29100 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
29110 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
29120 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
29130 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
29140 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
29150 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
29160 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79  led.  The memory
29170 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
29180 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
29190 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
291a0 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
291b0 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20    Do <b>not</b> 
291c0 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
291d0 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73  s returned.** [s
291e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
291f0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
29200 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
29210 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  etc. into.** [sq
29220 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
29230 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79  *.** If a memory
29240 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
29250 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
29260 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
29270 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
29280 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
29290 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
292a0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
292b0 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
292c0 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
292d0 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
292e0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
292f0 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
29300 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
29310 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
29320 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
29330 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
29340 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
29350 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  EM]..**.** INVAR
29360 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
29370 33 38 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  3803} The [sqlit
29380 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53  e3_column_blob(S
29390 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
293a0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
293b0 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
293c0 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
293d0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
293e0 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20  ult set for.**  
293f0 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65          the [pre
29400 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29410 20 53 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61   S into a BLOB a
29420 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
29430 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  a.**          po
29440 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e  inter to the con
29450 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a  verted value..**
29460 0a 2a 2a 20 7b 48 31 33 38 30 36 7d 20 54 68 65  .** {H13806} The
29470 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
29480 5f 62 79 74 65 73 28 53 2c 4e 29 5d 20 69 6e 74  _bytes(S,N)] int
29490 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
294a0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
294b0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
294c0 6e 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  n the BLOB or st
294d0 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20  ring (exclusive 
294e0 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
294f0 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74     zero terminat
29500 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67  or on the string
29510 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  ) that was retur
29520 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20  ned by the.**   
29530 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65         most rece
29540 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
29550 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
29560 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  S,N)] or.**     
29570 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
29580 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 2e  lumn_text(S,N)].
29590 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 39 7d 20  .**.** {H13809} 
295a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
295b0 75 6d 6e 5f 62 79 74 65 73 31 36 28 53 2c 4e 29  umn_bytes16(S,N)
295c0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
295d0 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rns the.**      
295e0 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79      number of by
295f0 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
29600 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20  g (exclusive of 
29610 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
29620 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
29630 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20 74  on the string) t
29640 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
29650 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   by the.**      
29660 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20      most recent 
29670 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
29680 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53  _column_text16(S
29690 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ,N)]..**.** {H13
296a0 38 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  812} The [sqlite
296b0 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
296c0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
296d0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
296e0 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
296f0 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
29700 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
29710 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65  sult set for the
29720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
29730 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29740 5d 20 53 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74  ] S into a float
29750 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
29760 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
29770 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
29780 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a  f that value..**
29790 0a 2a 2a 20 7b 48 31 33 38 31 35 7d 20 54 68 65  .** {H13815} The
297a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
297b0 5f 69 6e 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72  _int(S,N)] inter
297c0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
297d0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
297e0 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
297f0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
29800 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
29810 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
29820 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
29830 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
29840 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
29850 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20  teger and.**    
29860 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 74 68        returns th
29870 65 20 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20  e lower 32 bits 
29880 6f 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  of that integer.
29890 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 38 7d 20  .**.** {H13818} 
298a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
298b0 75 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e 29 5d 20  umn_int64(S,N)] 
298c0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
298d0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
298e0 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
298f0 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
29900 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
29910 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  et for the.**   
29920 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
29930 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
29940 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e  to a 64-bit sign
29950 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a  ed integer and.*
29960 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
29970 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61  ns a copy of tha
29980 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
29990 20 7b 48 31 33 38 32 31 7d 20 54 68 65 20 5b 73   {H13821} The [s
299a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
299b0 78 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  xt(S,N)] interfa
299c0 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
299d0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
299e0 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
299f0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
29a00 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a   result set for.
29a10 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
29a20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29a30 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65  ent] S into a ze
29a40 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
29a50 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  F-8.**          
29a60 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
29a70 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
29a80 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
29a90 2a 2a 20 7b 48 31 33 38 32 34 7d 20 54 68 65 20  ** {H13824} The 
29aa0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
29ab0 74 65 78 74 31 36 28 53 2c 4e 29 5d 20 69 6e 74  text16(S,N)] int
29ac0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
29ad0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
29ae0 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
29af0 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
29b00 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
29b10 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
29b20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
29b30 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20  atement] S into 
29b40 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
29b50 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
29b60 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
29b70 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
29b80 6f 72 64 65 72 20 73 74 72 69 6e 67 20 61 6e 64  order string and
29b90 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20   returns.**     
29ba0 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74       a pointer t
29bb0 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  o that string..*
29bc0 2a 0a 2a 2a 20 7b 48 31 33 38 32 37 7d 20 54 68  *.** {H13827} Th
29bd0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
29be0 6e 5f 74 79 70 65 28 53 2c 4e 29 5d 20 69 6e 74  n_type(S,N)] int
29bf0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
29c00 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f  *          one o
29c10 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c  f [SQLITE_NULL],
29c20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
29c30 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ], [SQLITE_FLOAT
29c40 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ],.**          [
29c50 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72  SQLITE_TEXT], or
29c60 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61   [SQLITE_BLOB] a
29c70 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f  s appropriate fo
29c80 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
29c90 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20  e Nth column in 
29ca0 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
29cb0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
29cc0 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
29cd0 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20    the [prepared 
29ce0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a  statement] S..**
29cf0 0a 2a 2a 20 7b 48 31 33 38 33 30 7d 20 54 68 65  .** {H13830} The
29d00 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
29d10 5f 76 61 6c 75 65 28 53 2c 4e 29 5d 20 69 6e 74  _value(S,N)] int
29d20 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
29d30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69  .**          poi
29d40 6e 74 65 72 20 74 6f 20 61 6e 20 5b 75 6e 70 72  nter to an [unpr
29d50 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29d60 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
29d70 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
29d80 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
29d90 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
29da0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
29db0 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  t for.**        
29dc0 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20    the [prepared 
29dd0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
29de0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
29df0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
29e00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29e10 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
29e20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
29e30 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
29e40 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
29e50 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
29e60 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
29e70 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
29e80 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
29e90 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
29ea0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29eb0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
29ec0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
29ed0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29ee0 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
29ef0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
29f00 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
29f10 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
29f20 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e   iCol);.const un
29f30 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
29f40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29f50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29f60 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
29f70 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
29f80 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
29f90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
29fa0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
29fb0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
29fc0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
29fd0 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
29fe0 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
29ff0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
2a000 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2a010 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
2a020 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
2a030 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2a040 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33  ment Object {H13
2a050 33 30 30 7d 20 3c 53 37 30 33 30 30 3e 3c 53 33  300} <S70300><S3
2a060 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0100>.**.** The 
2a070 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2a080 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
2a090 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
2a0a0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2a0b0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
2a0c0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
2a0d0 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73  executed success
2a0e0 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65  fully or not exe
2a0f0 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68  cuted at all, th
2a100 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20  en.** SQLITE_OK 
2a110 69 73 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20  is returned. If 
2a120 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
2a130 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65   statement faile
2a140 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72  d then an.** [er
2a150 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78  ror code] or [ex
2a160 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
2a170 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
2a180 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2a190 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
2a1a0 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
2a1b0 72 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ring the executi
2a1c0 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72  on of the.** [pr
2a1d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a1e0 5d 2e 20 20 49 66 20 74 68 65 20 76 69 72 74 75  ].  If the virtu
2a1f0 61 6c 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e  al machine has n
2a200 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  ot.** completed 
2a210 65 78 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74  execution when t
2a220 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63  his routine is c
2a230 61 6c 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c  alled, that is l
2a240 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ike.** encounter
2a250 69 6e 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  ing an error or 
2a260 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  an [sqlite3_inte
2a270 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70  rrupt | interrup
2a280 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74  t]..** Incomplet
2a290 65 20 75 70 64 61 74 65 73 20 6d 61 79 20 62 65  e updates may be
2a2a0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64   rolled back and
2a2b0 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61   transactions ca
2a2c0 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e  nceled,.** depen
2a2d0 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63  ding on the circ
2a2e0 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74  umstances, and t
2a2f0 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  he.** [error cod
2a300 65 5d 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c  e] returned will
2a310 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   be [SQLITE_ABOR
2a320 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  T]..**.** INVARI
2a330 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  ANTS:.**.** {H11
2a340 33 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  302} The [sqlite
2a350 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69  3_finalize(S)] i
2a360 6e 74 65 72 66 61 63 65 20 64 65 73 74 72 6f 79  nterface destroy
2a370 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2a380 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
2a390 65 6d 65 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c  ement] S and rel
2a3a0 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20  eases all.**    
2a3b0 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64        memory and
2a3c0 20 66 69 6c 65 20 72 65 73 6f 75 72 63 65 73 20   file resources 
2a3d0 68 65 6c 64 20 62 79 20 74 68 61 74 20 6f 62 6a  held by that obj
2a3e0 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  ect..**.** {H113
2a3f0 30 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20  04} If the most 
2a400 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2a410 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2a420 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
2a430 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
2a440 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
2a450 72 6e 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a  rned an error,.*
2a460 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
2a470 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2a480 65 28 53 29 5d 20 72 65 74 75 72 6e 73 20 74 68  e(S)] returns th
2a490 61 74 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a  at same error..*
2a4a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
2a4b0 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
2a4c0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2a4d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2a4e0 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
2a4f0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20  tatement Object 
2a500 7b 48 31 33 33 33 30 7d 20 3c 53 37 30 33 30 30  {H13330} <S70300
2a510 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
2a520 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63  te3_reset() func
2a530 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
2a540 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61  o reset a [prepa
2a550 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2a560 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f  * object back to
2a570 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
2a580 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
2a590 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
2a5a0 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
2a5b0 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
2a5c0 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
2a5d0 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
2a5e0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
2a5f0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
2a600 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
2a610 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
2a620 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
2a630 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
2a640 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
2a650 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
2a660 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 32 7d 20 54  **.** {H11332} T
2a670 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2a680 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2a690 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
2a6a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a6b0 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61  S.**          ba
2a6c0 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
2a6d0 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
2a6e0 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33  am..**.** {H1133
2a6f0 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  4} If the most r
2a700 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2a710 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2a720 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  for the.**      
2a730 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
2a740 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
2a750 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
2a760 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
2a770 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ],.**          o
2a780 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
2a790 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
2a7a0 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
2a7b0 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20  led on S,.**    
2a7c0 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69        then [sqli
2a7d0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
2a7e0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
2a7f0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 36  ]..**.** {H11336
2a800 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  } If the most re
2a810 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2a820 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2a830 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
2a840 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
2a850 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
2a860 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
2a870 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  en.**          [
2a880 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2a890 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
2a8a0 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
2a8b0 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  code]..**.** {H1
2a8c0 31 33 33 38 7d 20 54 68 65 20 5b 73 71 6c 69 74  1338} The [sqlit
2a8d0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
2a8e0 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
2a8f0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
2a900 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  s.**          of
2a910 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
2a920 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
2a930 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
2a940 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
2a950 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2a960 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
2a970 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2a980 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
2a990 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
2a9a0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48  SQL Functions {H
2a9b0 31 36 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a  16100} <S20200>.
2a9c0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75  ** KEYWORDS: {fu
2a9d0 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
2a9e0 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59  routines}.** KEY
2a9f0 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
2aa00 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2aa10 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59  function}.** KEY
2aa20 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
2aa30 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2aa40 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
2aa50 20 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63 74   These two funct
2aa60 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65  ions (collective
2aa70 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e  ly known as "fun
2aa80 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
2aa90 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65  outines").** are
2aaa0 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c   used to add SQL
2aab0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
2aac0 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72  gregates or to r
2aad0 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61  edefine the beha
2aae0 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74  vior.** of exist
2aaf0 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
2ab00 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e  s or aggregates.
2ab10 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65    The only diffe
2ab20 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20 74 68  rence between th
2ab30 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68 61 74  e.** two is that
2ab40 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
2ab50 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 6d 65 20  meter, the name 
2ab60 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29 20  of the (scalar) 
2ab70 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2ab80 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63  ggregate, is enc
2ab90 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f  oded in UTF-8 fo
2aba0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2abb0 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20  _function() and 
2abc0 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71  UTF-16.** for sq
2abd0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2abe0 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a  ction16()..**.**
2abf0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
2ac00 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
2ac10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2ac20 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
2ac30 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
2ac40 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
2ac50 49 66 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  If a single prog
2ac60 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ram uses more th
2ac70 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
2ac80 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e  ** connection in
2ac90 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53  ternally, then S
2aca0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
2acb0 74 20 62 65 20 61 64 64 65 64 20 69 6e 64 69 76  t be added indiv
2acc0 69 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61  idually to.** ea
2acd0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
2ace0 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  ection..**.** Th
2acf0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2ad00 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
2ad10 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
2ad20 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
2ad30 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
2ad40 2e 20 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66  .  The length of
2ad50 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
2ad60 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
2ad70 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a  s, exclusive of.
2ad80 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  ** the zero-term
2ad90 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68  inator.  Note th
2ada0 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67  at the name leng
2adb0 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62  th limit is in b
2adc0 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61  ytes, not.** cha
2add0 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74  racters.  Any at
2ade0 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
2adf0 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
2ae00 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
2ae10 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
2ae20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62  [SQLITE_ERROR] b
2ae30 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
2ae40 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70  *.** The third p
2ae50 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2ae60 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2ae70 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
2ae80 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2ae90 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
2aea0 20 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74   If this paramet
2aeb0 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
2aec0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
2aed0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
2aee0 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
2aef0 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
2af00 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  uments..**.** Th
2af10 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2af20 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
2af30 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
2af40 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
2af50 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
2af60 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
2af70 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
2af80 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
2af90 41 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  Any SQL function
2afa0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2afb0 73 68 6f 75 6c 64 20 62 65 20 61 62 6c 65 20 74  should be able t
2afc0 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77  o work.** work w
2afd0 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31  ith UTF-8, UTF-1
2afe0 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65  6le, or UTF-16be
2aff0 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c  .  But some impl
2b000 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
2b010 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63  be.** more effic
2b020 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e  ient with one en
2b030 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74  coding than anot
2b040 68 65 72 2e 20 20 49 74 20 69 73 20 61 6c 6c 6f  her.  It is allo
2b050 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  wed to.** invoke
2b060 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2b070 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71  function() or sq
2b080 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2b090 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70  ction16() multip
2b0a0 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
2b0b0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2b0c0 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66  on but with diff
2b0d0 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20  erent values of 
2b0e0 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65  eTextRep..** Whe
2b0f0 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
2b100 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
2b110 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2b120 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
2b130 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
2b140 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
2b150 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
2b160 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
2b170 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
2b180 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
2b190 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
2b1a0 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
2b1b0 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
2b1c0 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64  at text.** encod
2b1d0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
2b1e0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
2b1f0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
2b200 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a  [SQLITE_ANY]..**
2b210 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61  .** The fifth pa
2b220 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
2b230 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
2b240 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
2b250 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
2b260 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
2b270 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
2b280 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
2b290 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
2b2a0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ()]..**.** The s
2b2b0 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61  eventh, eighth a
2b2c0 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  nd ninth paramet
2b2d0 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
2b2e0 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
2b2f0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
2b300 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
2b310 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
2b320 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
2b330 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
2b340 65 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20  egate. A scalar 
2b350 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
2b360 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
2b370 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
2b380 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
2b390 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e   only, NULL poin
2b3a0 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70  ters should be p
2b3b0 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
2b3c0 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a  ep and xFinal.**
2b3d0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20   parameters. An 
2b3e0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
2b3f0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
2b400 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
2b410 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
2b420 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
2b430 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73  L should be pass
2b440 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f  ed for xFunc. To
2b450 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
2b460 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
2b470 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
2b480 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20  , pass NULL for 
2b490 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
2b4a0 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  on callbacks..**
2b4b0 0a 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74  .** It is permit
2b4c0 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
2b4d0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2b4e0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2b4f0 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
2b500 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
2b510 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
2b520 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
2b530 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
2b540 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
2b550 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
2b560 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53  xt encodings.  S
2b570 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
2b580 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
2b590 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  tion most closel
2b5a0 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
2b5b0 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
2b5c0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
2b5d0 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  s used..**.** IN
2b5e0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2b5f0 7b 48 31 36 31 30 33 7d 20 54 68 65 20 5b 73 71  {H16103} The [sq
2b600 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2b610 63 74 69 6f 6e 31 36 28 29 5d 20 69 6e 74 65 72  ction16()] inter
2b620 66 61 63 65 20 62 65 68 61 76 65 73 20 65 78 61  face behaves exa
2b630 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ctly.**         
2b640 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 63   like [sqlite3_c
2b650 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2b660 5d 20 69 6e 20 65 76 65 72 79 20 77 61 79 20 65  ] in every way e
2b670 78 63 65 70 74 20 74 68 61 74 20 69 74 0a 2a 2a  xcept that it.**
2b680 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 70            interp
2b690 72 65 74 73 20 74 68 65 20 7a 46 75 6e 63 74 69  rets the zFuncti
2b6a0 6f 6e 4e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  onName argument 
2b6b0 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  as zero-terminat
2b6c0 65 64 20 55 54 46 2d 31 36 0a 2a 2a 20 20 20 20  ed UTF-16.**    
2b6d0 20 20 20 20 20 20 6e 61 74 69 76 65 20 62 79 74        native byt
2b6e0 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20  e order instead 
2b6f0 6f 66 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69  of as zero-termi
2b700 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a 2a 2a 0a  nated UTF-8..**.
2b710 2a 2a 20 7b 48 31 36 31 30 36 7d 20 41 20 73 75  ** {H16106} A su
2b720 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
2b730 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ion of.**       
2b740 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
2b750 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2b760 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 20 69 6e  D,X,N,E,...)] in
2b770 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
2b780 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  s.**          or
2b790 20 72 65 70 6c 61 63 65 73 20 63 61 6c 6c 62 61   replaces callba
2b7a0 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20  ck functions in 
2b7b0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2b7c0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20  nnection] D.**  
2b7d0 20 20 20 20 20 20 20 20 75 73 65 64 20 74 6f 20          used to 
2b7e0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
2b7f0 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 64  L function named
2b800 20 58 20 77 69 74 68 20 4e 20 70 61 72 61 6d 65   X with N parame
2b810 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ters.**         
2b820 20 61 6e 64 20 68 61 76 69 6e 67 20 61 20 70 72   and having a pr
2b830 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2b840 6f 64 69 6e 67 20 6f 66 20 45 2e 0a 2a 2a 0a 2a  oding of E..**.*
2b850 2a 20 7b 48 31 36 31 30 39 7d 20 41 20 73 75 63  * {H16109} A suc
2b860 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2b870 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2b880 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
2b890 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20  ,P,F,S,L)].**   
2b8a0 20 20 20 20 20 20 20 72 65 70 6c 61 63 65 73 20         replaces 
2b8b0 74 68 65 20 50 2c 20 46 2c 20 53 2c 20 61 6e 64  the P, F, S, and
2b8c0 20 4c 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 61   L values from a
2b8d0 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77  ny prior calls w
2b8e0 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
2b8f0 74 68 65 20 73 61 6d 65 20 44 2c 20 58 2c 20 4e  the same D, X, N
2b900 2c 20 61 6e 64 20 45 20 76 61 6c 75 65 73 2e 0a  , and E values..
2b910 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 32 7d 20 54  **.** {H16112} T
2b920 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2b930 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2b940 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ...)] interface 
2b950 66 61 69 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20  fails with.**   
2b960 20 20 20 20 20 20 20 61 20 72 65 74 75 72 6e 20         a return 
2b970 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
2b980 45 52 52 4f 52 5d 20 69 66 20 74 68 65 20 53 51  ERROR] if the SQ
2b990 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 20  L function name 
2b9a0 58 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  X is.**         
2b9b0 20 6c 6f 6e 67 65 72 20 74 68 61 6e 20 32 35 35   longer than 255
2b9c0 20 62 79 74 65 73 20 65 78 63 6c 75 73 69 76 65   bytes exclusive
2b9d0 20 6f 66 20 74 68 65 20 7a 65 72 6f 20 74 65 72   of the zero ter
2b9e0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b  minator..**.** {
2b9f0 48 31 36 31 31 38 7d 20 45 69 74 68 65 72 20 46  H16118} Either F
2ba00 20 6d 75 73 74 20 62 65 20 4e 55 4c 4c 20 61 6e   must be NULL an
2ba10 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20 6e 6f  d S and L are no
2ba20 6e 2d 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 46  n-NULL or else F
2ba30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
2ba40 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20 53 20 61  non-NULL and S a
2ba50 6e 64 20 4c 20 61 72 65 20 4e 55 4c 4c 2c 20 6f  nd L are NULL, o
2ba60 74 68 65 72 77 69 73 65 0a 2a 2a 20 20 20 20 20  therwise.**     
2ba70 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72       [sqlite3_cr
2ba80 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2ba90 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 20  X,N,E,P,F,S,L)] 
2baa0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
2bab0 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ERROR]..**.** {H
2bac0 31 36 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69  16121} The [sqli
2bad0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2bae0 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65  ion(D,...)] inte
2baf0 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
2bb00 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
2bb10 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53  error code of [S
2bb20 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 66 20 74  QLITE_BUSY] if t
2bb30 68 65 72 65 20 65 78 69 73 74 20 5b 70 72 65 70  here exist [prep
2bb40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2bb50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73  .**          ass
2bb60 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
2bb70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2bb80 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
2bb90 7b 48 31 36 31 32 34 7d 20 54 68 65 20 5b 73 71  {H16124} The [sq
2bba0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2bbb0 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29  ction(D,X,N,...)
2bbc0 5d 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  ] interface fail
2bbd0 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20  s with an.**    
2bbe0 20 20 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65        error code
2bbf0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f   of [SQLITE_ERRO
2bc00 52 5d 20 69 66 20 70 61 72 61 6d 65 74 65 72 20  R] if parameter 
2bc10 4e 20 28 73 70 65 63 69 66 79 69 6e 67 20 74 68  N (specifying th
2bc20 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20  e number.**     
2bc30 20 20 20 20 20 6f 66 20 61 72 67 75 6d 65 6e 74       of argument
2bc40 73 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  s to the SQL fun
2bc50 63 74 69 6f 6e 20 62 65 69 6e 67 20 72 65 67 69  ction being regi
2bc60 73 74 65 72 65 64 29 20 69 73 20 6c 65 73 73 0a  stered) is less.
2bc70 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 6e  **          than
2bc80 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
2bc90 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a 2a 20 7b  han 127..**.** {
2bca0 48 31 36 31 32 37 7d 20 57 68 65 6e 20 4e 20 69  H16127} When N i
2bcb0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
2bcc0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
2bcd0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2bce0 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  ,N,...)].**     
2bcf0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63       interface c
2bd00 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 73 20  auses callbacks 
2bd10 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f  to be invoked fo
2bd20 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  r the SQL functi
2bd30 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  on.**          n
2bd40 61 6d 65 64 20 58 20 77 68 65 6e 20 74 68 65 20  amed X when the 
2bd50 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2bd60 6e 74 73 20 74 6f 20 74 68 65 20 53 51 4c 20 66  nts to the SQL f
2bd70 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20  unction is.**   
2bd80 20 20 20 20 20 20 20 65 78 61 63 74 6c 79 20 4e         exactly N
2bd90 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 30 7d  ..**.** {H16130}
2bda0 20 57 68 65 6e 20 4e 20 69 73 20 2d 31 2c 20 74   When N is -1, t
2bdb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2bdc0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2bdd0 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  N,...)].**      
2bde0 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61      interface ca
2bdf0 75 73 65 73 20 63 61 6c 6c 62 61 63 6b 73 20 74  uses callbacks t
2be00 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f 72  o be invoked for
2be10 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2be20 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61  n.**          na
2be30 6d 65 64 20 58 20 77 69 74 68 20 61 6e 79 20 6e  med X with any n
2be40 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2be50 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33  ts..**.** {H1613
2be60 33 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f  3} When calls to
2be70 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2be80 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c  _function(D,X,N,
2be90 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
2bea0 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69 70    specify multip
2beb0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2bec0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
2bed0 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 20 20 20  unction X.**    
2bee0 20 20 20 20 20 20 61 6e 64 20 77 68 65 6e 20 6f        and when o
2bef0 6e 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ne implementatio
2bf00 6e 20 68 61 73 20 4e 3e 3d 30 20 61 6e 64 20 74  n has N>=0 and t
2bf10 68 65 20 6f 74 68 65 72 20 68 61 73 20 4e 3d 28  he other has N=(
2bf20 2d 31 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  -1).**          
2bf30 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
2bf40 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  on with a non-ze
2bf50 72 6f 20 4e 20 69 73 20 70 72 65 66 65 72 72 65  ro N is preferre
2bf60 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 36  d..**.** {H16136
2bf70 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  } When calls to 
2bf80 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2bf90 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
2bfa0 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
2bfb0 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c 74 69     specify multi
2bfc0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
2bfd0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
2bfe0 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 0a  function X with.
2bff0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2c000 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f 66 20 61  same number of a
2c010 72 67 75 6d 65 6e 74 73 20 4e 20 62 75 74 20 77  rguments N but w
2c020 69 74 68 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a  ith different.**
2c030 20 20 20 20 20 20 20 20 20 20 65 6e 63 6f 64 69            encodi
2c040 6e 67 73 20 45 2c 20 74 68 65 6e 20 74 68 65 20  ngs E, then the 
2c050 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2c060 68 65 72 65 20 45 20 6d 61 74 63 68 65 73 20 74  here E matches t
2c070 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  he.**          d
2c080 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
2c090 20 69 73 20 70 72 65 66 65 72 72 65 64 2e 0a 2a   is preferred..*
2c0a0 2a 0a 2a 2a 20 7b 48 31 36 31 33 39 7d 20 46 6f  *.** {H16139} Fo
2c0b0 72 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 53  r an aggregate S
2c0c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  QL function crea
2c0d0 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  ted using.**    
2c0e0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
2c0f0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2c100 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d  ,X,N,E,P,0,S,L)]
2c110 20 74 68 65 20 66 69 6e 61 6c 69 7a 65 72 0a 2a   the finalizer.*
2c120 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e 63 74  *          funct
2c130 69 6f 6e 20 4c 20 77 69 6c 6c 20 61 6c 77 61 79  ion L will alway
2c140 73 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 78 61  s be invoked exa
2c150 63 74 6c 79 20 6f 6e 63 65 20 69 66 20 74 68 65  ctly once if the
2c160 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 65  .**          ste
2c170 70 20 66 75 6e 63 74 69 6f 6e 20 53 20 69 73 20  p function S is 
2c180 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
2c190 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20  re times..**.** 
2c1a0 7b 48 31 36 31 34 32 7d 20 57 68 65 6e 20 53 51  {H16142} When SQ
2c1b0 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 65 69 74  Lite invokes eit
2c1c0 68 65 72 20 74 68 65 20 78 46 75 6e 63 20 6f 72  her the xFunc or
2c1d0 20 78 53 74 65 70 20 66 75 6e 63 74 69 6f 6e 20   xStep function 
2c1e0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  of.**          a
2c1f0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
2c200 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2c210 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 20  on or aggregate 
2c220 63 72 65 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  created.**      
2c230 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f      by [sqlite3_
2c240 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2c250 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63  )] or [sqlite3_c
2c260 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2c270 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
2c280 20 74 68 65 6e 20 74 68 65 20 61 72 72 61 79 20   then the array 
2c290 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  of [sqlite3_valu
2c2a0 65 5d 20 6f 62 6a 65 63 74 73 20 70 61 73 73 65  e] objects passe
2c2b0 64 20 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  d as the.**     
2c2c0 20 20 20 20 20 74 68 69 72 64 20 70 61 72 61 6d       third param
2c2d0 65 74 65 72 20 61 72 65 20 61 6c 77 61 79 73 20  eter are always 
2c2e0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2c2f0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2c300 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
2c310 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2c320 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
2c330 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
2c340 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2c350 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2c360 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2c370 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2c380 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2c390 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2c3a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2c3b0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2c3c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2c3d0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2c3e0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2c3f0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2c400 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
2c410 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2c420 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71  function16(.  sq
2c430 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
2c440 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69  st void *zFuncti
2c450 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
2c460 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
2c470 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
2c480 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
2c490 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2c4a0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2c4b0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2c4c0 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
2c4d0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2c4e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2c4f0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
2c500 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2c510 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
2c520 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
2c530 64 69 6e 67 73 20 7b 48 31 30 32 36 37 7d 20 3c  dings {H10267} <
2c540 53 35 30 32 30 30 3e 20 3c 48 31 36 31 30 30 3e  S50200> <H16100>
2c550 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2c560 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
2c570 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
2c580 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
2c590 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
2c5a0 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
2c5b0 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
2c5c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2c5d0 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a  TF8           1.
2c5e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2c5f0 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a  TF16LE        2.
2c600 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2c610 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a  TF16BE        3.
2c620 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
2c630 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
2c640 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
2c650 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
2c660 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
2c670 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
2c680 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
2c690 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c  ate_function onl
2c6a0 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
2c6b0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
2c6c0 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74  D  8    /* sqlit
2c6d0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2c6e0 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a  ion only */../*.
2c6f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 73  ** CAPI3REF: Obs
2c700 6f 6c 65 74 65 20 46 75 6e 63 74 69 6f 6e 73 0a  olete Functions.
2c710 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
2c720 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 20 6e 6f  tions are all no
2c730 77 20 6f 62 73 6f 6c 65 74 65 2e 20 20 49 6e 20  w obsolete.  In 
2c740 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
2c750 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
2c760 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
2c770 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 77 65  h older code, we
2c780 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 73 75 70   continue to sup
2c790 70 6f 72 74 0a 2a 2a 20 74 68 65 73 65 20 66 75  port.** these fu
2c7a0 6e 63 74 69 6f 6e 73 2e 20 20 48 6f 77 65 76 65  nctions.  Howeve
2c7b0 72 2c 20 6e 65 77 20 64 65 76 65 6c 6f 70 6d 65  r, new developme
2c7c0 6e 74 20 70 72 6f 6a 65 63 74 73 20 73 68 6f 75  nt projects shou
2c7d0 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
2c7e0 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
2c7f0 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70  ctions.  To help
2c800 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c   encourage peopl
2c810 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73  e to avoid.** us
2c820 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69  ing these functi
2c830 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20  ons, we are not 
2c840 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f  going to tell yo
2c850 75 20 77 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a  u want they do..
2c860 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  */.int sqlite3_a
2c870 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
2c880 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2c890 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  ;.int sqlite3_ex
2c8a0 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
2c8b0 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  mt*);.int sqlite
2c8c0 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
2c8d0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
2c8e0 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
2c8f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  );.int sqlite3_g
2c900 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
2c910 69 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  id);.void sqlite
2c920 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70  3_thread_cleanup
2c930 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
2c940 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
2c950 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73  (void(*)(void*,s
2c960 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74  qlite3_int64,int
2c970 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  ),void*,sqlite3_
2c980 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int64);../*.** C
2c990 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
2c9a0 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  ng SQL Function 
2c9b0 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73  Parameter Values
2c9c0 20 7b 48 31 35 31 30 30 7d 20 3c 53 32 30 32 30   {H15100} <S2020
2c9d0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  0>.**.** The C-l
2c9e0 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
2c9f0 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
2ca00 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
2ca10 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
2ca20 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
2ca30 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
2ca40 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
2ca50 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
2ca60 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
2ca70 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
2ca80 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
2ca90 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
2caa0 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
2cab0 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
2cac0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
2cad0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2cae0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
2caf0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2cb00 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
2cb10 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
2cb20 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
2cb30 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2cb40 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
2cb50 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61  s..** The 4th pa
2cb60 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
2cb70 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
2cb80 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
2cb90 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
2cba0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2cbb0 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
2cbc0 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
2cbd0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2cbe0 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
2cbf0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
2cc00 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
2cc10 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2cc20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
2cc30 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
2cc40 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2cc50 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
2cc60 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2cc70 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
2cc80 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2cc90 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2cca0 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
2ccb0 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
2ccc0 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
2ccd0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2cce0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
2ccf0 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
2cd00 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
2cd10 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  r..**.** These r
2cd20 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
2cd30 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
2cd40 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
2cd50 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2cd60 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
2cd70 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  t  these routine
2cd80 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
2cd90 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2cda0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2cdb0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
2cdc0 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
2cdd0 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
2cde0 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
2cdf0 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
2ce00 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2ce10 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
2ce20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
2ce30 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
2ce40 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
2ce50 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
2ce60 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
2ce70 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ne.  The.** sqli
2ce80 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2ce90 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
2cea0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
2ceb0 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
2cec0 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
2ced0 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
2cee0 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
2cef0 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
2cf00 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
2cf10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
2cf20 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
2cf30 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
2cf40 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
2cf50 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
2cf60 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
2cf70 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
2cf80 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
2cf90 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
2cfa0 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
2cfb0 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
2cfc0 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
2cfd0 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
2cfe0 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
2cff0 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
2d000 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
2d010 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
2d020 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
2d030 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
2d040 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
2d050 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
2d060 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
2d070 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
2d080 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
2d090 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
2d0a0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
2d0b0 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
2d0c0 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
2d0d0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  rned..**.** Plea
2d0e0 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
2d0f0 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
2d100 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
2d110 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65   pointer returne
2d120 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
2d130 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
2d140 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2d150 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
2d160 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2d170 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
2d180 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
2d190 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
2d1a0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2d1b0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
2d1c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2d1d0 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
2d1e0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
2d1f0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
2d200 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
2d210 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ]..**.** These r
2d220 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
2d230 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
2d240 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
2d250 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
2d260 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
2d270 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2d280 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
2d290 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2d2a0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30  TS:.**.** {H1510
2d2b0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
2d2c0 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 69  value_blob(V)] i
2d2d0 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2d2e0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2d2f0 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2d300 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2d310 63 74 20 56 20 69 6e 74 6f 20 61 20 42 4c 4f 42  ct V into a BLOB
2d320 20 61 6e 64 20 74 68 65 6e 0a 2a 2a 20 20 20 20   and then.**    
2d330 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
2d340 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
2d350 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a  onverted value..
2d360 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 36 7d 20 54  **.** {H15106} T
2d370 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2d380 65 5f 62 79 74 65 73 28 56 29 5d 20 69 6e 74 65  e_bytes(V)] inte
2d390 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2d3a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
2d3b0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2d3c0 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
2d3d0 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f  ing (exclusive o
2d3e0 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2d3f0 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f    zero terminato
2d400 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29  r on the string)
2d410 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
2d420 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
2d430 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e        most recen
2d440 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2d450 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29  e3_value_blob(V)
2d460 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
2d470 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2d480 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20  text(V)]..**.** 
2d490 7b 48 31 35 31 30 39 7d 20 54 68 65 20 5b 73 71  {H15109} The [sq
2d4a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2d4b0 73 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63  s16(V)] interfac
2d4c0 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2d4d0 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
2d4e0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2d4f0 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69   string (exclusi
2d500 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ve of the.**    
2d510 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69        zero termi
2d520 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72  nator on the str
2d530 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65  ing) that was re
2d540 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
2d550 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72            most r
2d560 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2d570 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2d580 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20 20 20 20  t16(V)],.**     
2d590 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61       [sqlite3_va
2d5a0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d  lue_text16be(V)]
2d5b0 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  , or [sqlite3_va
2d5c0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d  lue_text16le(V)]
2d5d0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 32 7d  ..**.** {H15112}
2d5e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2d5f0 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29 5d 20 69  lue_double(V)] i
2d600 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2d610 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2d620 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2d630 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2d640 63 74 20 56 20 69 6e 74 6f 20 61 20 66 6c 6f 61  ct V into a floa
2d650 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2d660 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
2d670 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
2d680 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a  of that value..*
2d690 2a 0a 2a 2a 20 7b 48 31 35 31 31 35 7d 20 54 68  *.** {H15115} Th
2d6a0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2d6b0 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65 72 66 61  _int(V)] interfa
2d6c0 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2d6d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f  **          [pro
2d6e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2d6f0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
2d700 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67  nto a 64-bit sig
2d710 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a  ned integer and.
2d720 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2d730 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32  rns the lower 32
2d740 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e   bits of that in
2d750 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  teger..**.** {H1
2d760 35 31 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74  5118} The [sqlit
2d770 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 56  e3_value_int64(V
2d780 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2d790 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2d7a0 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
2d7b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2d7c0 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
2d7d0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2d7e0 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20  teger and.**    
2d7f0 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
2d800 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74  copy of that int
2d810 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  eger..**.** {H15
2d820 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  121} The [sqlite
2d830 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d  3_value_text(V)]
2d840 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2d850 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2d860 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2d870 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2d880 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65  ject V into a ze
2d890 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
2d8a0 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  F-8.**          
2d8b0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2d8c0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2d8d0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
2d8e0 2a 2a 20 7b 48 31 35 31 32 34 7d 20 54 68 65 20  ** {H15124} The 
2d8f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2d900 65 78 74 31 36 28 56 29 5d 20 69 6e 74 65 72 66  ext16(V)] interf
2d910 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2d920 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2d930 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2d940 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
2d950 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
2d960 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a  inated 2-byte.**
2d970 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65            aligne
2d980 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  d UTF-16 native 
2d990 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
2d9a0 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
2d9b0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
2d9c0 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
2d9d0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32  ng..**.** {H1512
2d9e0 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
2d9f0 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56  value_text16be(V
2da00 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2da10 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2da20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
2da30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2da40 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
2da50 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2da60 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20  2-byte.**       
2da70 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31     aligned UTF-1
2da80 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20  6 big-endian.** 
2da90 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2daa0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
2dab0 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
2dac0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ring..**.** {H15
2dad0 31 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  130} The [sqlite
2dae0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
2daf0 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2db00 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2db10 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
2db20 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2db30 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2db40 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2db50 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
2db60 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
2db70 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  -16 little-endia
2db80 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  n.**          st
2db90 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2dba0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2dbb0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
2dbc0 20 7b 48 31 35 31 33 33 7d 20 54 68 65 20 5b 73   {H15133} The [s
2dbd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
2dbe0 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(V)] interface 
2dbf0 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
2dc00 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49      one of [SQLI
2dc10 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_NULL], [SQLIT
2dc20 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c  E_INTEGER], [SQL
2dc30 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20  ITE_FLOAT],.**  
2dc40 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
2dc50 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  TEXT], or [SQLIT
2dc60 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f  E_BLOB] as appro
2dc70 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20  priate for.**   
2dc80 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69         the [sqli
2dc90 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2dca0 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  t V..**.** {H151
2dcb0 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  36} The [sqlite3
2dcc0 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
2dcd0 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  ype(V)] interfac
2dce0 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 20 20  e converts.**   
2dcf0 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 6f 74         the [prot
2dd00 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2dd10 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
2dd20 74 6f 20 65 69 74 68 65 72 20 61 6e 20 69 6e 74  to either an int
2dd30 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20 20 20 20  eger or.**      
2dd40 20 20 20 20 61 20 66 6c 6f 61 74 69 6e 67 20 70      a floating p
2dd50 6f 69 6e 74 20 76 61 6c 75 65 20 69 66 20 69 74  oint value if it
2dd60 20 63 61 6e 20 64 6f 20 73 6f 20 77 69 74 68 6f   can do so witho
2dd70 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a 20 20 20  ut loss of.**   
2dd80 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61 74 69         informati
2dd90 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  on, and returns 
2dda0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e  one of [SQLITE_N
2ddb0 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ULL],.**        
2ddc0 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45    [SQLITE_INTEGE
2ddd0 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  R], [SQLITE_FLOA
2dde0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
2ddf0 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
2de00 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20    [SQLITE_BLOB] 
2de10 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  as appropriate f
2de20 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
2de30 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
2de40 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2de50 65 63 74 20 56 20 61 66 74 65 72 20 74 68 65 20  ect V after the 
2de60 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74 74 65 6d  conversion attem
2de70 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  pt..*/.const voi
2de80 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2de90 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
2dea0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2deb0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
2dec0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2ded0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2dee0 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
2def0 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
2df00 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
2df10 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
2df20 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2df30 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
2df40 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
2df50 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
2df60 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
2df70 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2df80 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
2df90 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
2dfa0 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
2dfb0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
2dfc0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
2dfd0 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
2dfe0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
2dff0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2e000 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
2e010 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2e020 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2e030 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2e040 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
2e050 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2e060 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
2e070 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2e080 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
2e090 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
2e0a0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
2e0b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
2e0c0 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
2e0d0 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
2e0e0 7b 48 31 36 32 31 30 7d 20 3c 53 32 30 32 30 30  {H16210} <S20200
2e0f0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c  >.**.** The impl
2e100 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67  ementation of ag
2e110 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
2e120 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72  tions use this r
2e130 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
2e140 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72  te.** a structur
2e150 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  e for storing th
2e160 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
2e170 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   The first time 
2e180 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
2e190 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2e1a0 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
2e1b0 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69  d for a.** parti
2e1c0 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c  cular aggregate,
2e1d0 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65   SQLite allocate
2e1e0 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f  s nBytes of memo
2e1f0 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
2e200 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61  hat.** memory, a
2e210 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
2e220 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73  nter to it. On s
2e230 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
2e240 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
2e250 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2e260 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
2e270 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
2e280 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64  ate function ind
2e290 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ex,.** the same 
2e2a0 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
2e2b0 65 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  ed. The implemen
2e2c0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 61 67  tation of the ag
2e2d0 67 72 65 67 61 74 65 20 63 61 6e 20 75 73 65 0a  gregate can use.
2e2e0 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 65 64 20  ** the returned 
2e2f0 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75  buffer to accumu
2e300 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  late data..**.**
2e310 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
2e320 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
2e330 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72  allocated buffer
2e340 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
2e350 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e  ate.** query con
2e360 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
2e370 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2e380 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f  r should be a co
2e390 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
2e3a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
2e3b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
2e3c0 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
2e3d0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2e3e0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
2e3f0 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
2e400 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
2e410 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2e420 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
2e430 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
2e440 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
2e450 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
2e460 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
2e470 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2e480 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
2e490 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2e4a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 31 7d 20  .**.** {H16211} 
2e4b0 54 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61  The first invoca
2e4c0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
2e4d0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2e4e0 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20  xt(C,N)] for.** 
2e4f0 20 20 20 20 20 20 20 20 20 61 20 70 61 72 74 69           a parti
2e500 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f  cular instance o
2e510 66 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 66  f an aggregate f
2e520 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61 20 70  unction (for a p
2e530 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20  articular.**    
2e540 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 29        context C)
2e550 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
2e560 6f 20 61 6c 6c 6f 63 61 74 65 20 4e 20 62 79 74  o allocate N byt
2e570 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  es of memory,.**
2e580 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
2e590 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
2e5a0 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72  return a pointer
2e5b0 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   to the allocate
2e5c0 64 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  d memory..**.** 
2e5d0 7b 48 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65  {H16213} If a me
2e5e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2e5f0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
2e600 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
2e610 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
2e620 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d  te_context(C,N)]
2e630 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   then the functi
2e640 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  on returns 0..**
2e650 0a 2a 2a 20 7b 48 31 36 32 31 35 7d 20 53 65 63  .** {H16215} Sec
2e660 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2e670 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  nt invocations o
2e680 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  f.**          [s
2e690 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2e6a0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66  _context(C,N)] f
2e6b0 6f 72 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74  or the same cont
2e6c0 65 78 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a  ext pointer C.**
2e6d0 20 20 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65            ignore
2e6e0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
2e6f0 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f   and return a po
2e700 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d  inter to the sam
2e710 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c  e.**          bl
2e720 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65  ock of memory re
2e730 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 66 69  turned by the fi
2e740 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a  rst invocation..
2e750 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 37 7d 20 54  **.** {H16217} T
2e760 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
2e770 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ted by [sqlite3_
2e780 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2e790 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20  t(C,N)] is.**   
2e7a0 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63         automatic
2e7b0 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68  ally freed on th
2e7c0 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b  e next call to [
2e7d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e7e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
2e7f0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2e800 65 28 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72  e()] for the [pr
2e810 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e820 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20  ] containing.** 
2e830 20 20 20 20 20 20 20 20 20 74 68 65 20 61 67 67           the agg
2e840 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
2e850 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2e860 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f  context C..*/.vo
2e870 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
2e880 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
2e890 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2e8a0 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
2e8b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
2e8c0 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
2e8d0 74 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c  tions {H16240} <
2e8e0 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
2e8f0 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
2e900 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
2e910 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2e920 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
2e930 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
2e940 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
2e950 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
2e960 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
2e970 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2e980 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
2e990 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2e9a0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2e9b0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
2e9c0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
2e9d0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
2e9e0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
2e9f0 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a  function. {END}.
2ea00 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2ea10 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
2ea20 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2ea30 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2ea40 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2ea50 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2ea60 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2ea70 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2ea80 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 34 33 7d  :.**.** {H16243}
2ea90 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 73   The [sqlite3_us
2eaa0 65 72 5f 64 61 74 61 28 43 29 5d 20 69 6e 74 65  er_data(C)] inte
2eab0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2eac0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20  copy of the.**  
2ead0 20 20 20 20 20 20 20 20 50 20 70 6f 69 6e 74 65          P pointe
2eae0 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  r from the [sqli
2eaf0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2eb00 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  ion(D,X,N,E,P,F,
2eb10 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,L)].**        
2eb20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72    or [sqlite3_cr
2eb30 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2eb40 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
2eb50 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20  ] call that.**  
2eb60 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
2eb70 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ed the SQL funct
2eb80 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77  ion associated w
2eb90 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ith [sqlite3_con
2eba0 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64  text] C..*/.void
2ebb0 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   *sqlite3_user_d
2ebc0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
2ebd0 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
2ebe0 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2ebf0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20   Connection For 
2ec00 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 35  Functions {H1625
2ec10 30 7d 20 3c 53 36 30 36 30 30 3e 3c 53 32 30 32  0} <S60600><S202
2ec20 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
2ec30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2ec40 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
2ec50 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
2ec60 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
2ec70 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
2ec80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2ec90 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
2eca0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
2ecb0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2ecc0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
2ecd0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2ece0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2ecf0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
2ed00 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
2ed10 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
2ed20 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
2ed30 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2ed40 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2ed50 2a 20 7b 48 31 36 32 35 33 7d 20 54 68 65 20 5b  * {H16253} The [
2ed60 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
2ed70 64 62 5f 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e  db_handle(C)] in
2ed80 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2ed90 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
2eda0 20 20 20 20 20 20 20 20 20 20 44 20 70 6f 69 6e            D poin
2edb0 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ter from the [sq
2edc0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2edd0 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
2ede0 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20  F,S,L)].**      
2edf0 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
2ee00 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2ee10 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  6(D,X,N,E,P,F,S,
2ee20 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a  L)] call that.**
2ee30 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
2ee40 65 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e  ered the SQL fun
2ee50 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64  ction associated
2ee60 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63   with [sqlite3_c
2ee70 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71  ontext] C..*/.sq
2ee80 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
2ee90 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
2eea0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2eeb0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2eec0 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
2eed0 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b 48 31  xiliary Data {H1
2eee0 36 32 37 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  6270} <S20200>.*
2eef0 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
2ef00 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
2ef10 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
2ef20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
2ef30 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
2ef40 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
2ef50 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
2ef60 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
2ef70 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
2ef80 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
2ef90 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
2efa0 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
2efb0 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
2efc0 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
2efd0 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
2efe0 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
2eff0 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
2f000 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
2f010 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65  . This may.** be
2f020 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70   used, for examp
2f030 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67  le, to add a reg
2f040 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
2f050 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a  matching scalar.
2f060 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
2f070 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
2f080 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
2f090 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73   expression is s
2f0a0 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
2f0b0 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
2f0c0 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
2f0d0 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
2f0e0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
2f0f0 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
2f100 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
2f110 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
2f120 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
2f130 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
2f140 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
2f150 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
2f160 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
2f170 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
2f180 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
2f190 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
2f1a0 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
2f1b0 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  ocation..**.** T
2f1c0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
2f1d0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
2f1e0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2f1f0 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
2f200 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
2f210 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
2f220 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
2f230 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68  function with th
2f240 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  e Nth argument.*
2f250 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61  * value to the a
2f260 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2f270 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20  ed function. If 
2f280 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  no metadata has 
2f290 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65  been ever.** bee
2f2a0 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74  n set for the Nt
2f2b0 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  h argument of th
2f2c0 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
2f2d0 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
2f2e0 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
2f2f0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68  parameter has ch
2f300 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
2f310 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
2f320 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  t,.** then sqlit
2f330 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2f340 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
2f350 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
2f360 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
2f370 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
2f380 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74  ce saves the met
2f390 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  adata.** pointed
2f3a0 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
2f3b0 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
2f3c0 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
2f3d0 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
2f3e0 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
2f3f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2f400 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65  ction.  Subseque
2f410 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
2f420 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2f430 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72  ta() might retur
2f440 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20  n this data, if 
2f450 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65  it has.** not be
2f460 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  en destroyed..**
2f470 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55   If it is not NU
2f480 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
2f490 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
2f4a0 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  uctor.** functio
2f4b0 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34  n given by the 4
2f4c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2f4d0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2f4e0 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20  ata() on.** the 
2f4f0 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68  metadata when th
2f500 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2f510 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
2f520 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72  er changes.** or
2f530 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   when the SQL st
2f540 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65  atement complete
2f550 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  s, whichever com
2f560 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
2f570 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
2f580 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72  o call the destr
2f590 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d  uctor and drop m
2f5a0 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a  etadata on any.*
2f5b0 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61  * parameter of a
2f5c0 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61  ny function at a
2f5d0 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e  ny time.  The on
2f5e0 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20  ly guarantee is 
2f5f0 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74  that.** the dest
2f600 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63  ructor will be c
2f610 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65  alled before the
2f620 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f   metadata is dro
2f630 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70  pped..**.** In p
2f640 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74  ractice, metadat
2f650 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62  a is preserved b
2f660 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20  etween function 
2f670 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70  calls for.** exp
2f680 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72  ressions that ar
2f690 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f  e constant at co
2f6a0 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73  mpile time. This
2f6b0 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61   includes litera
2f6c0 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
2f6d0 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a  SQL variables..*
2f6e0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2f6f0 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
2f700 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2f710 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2f720 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
2f730 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2f740 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2f750 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 32  S:.**.** {H16272
2f760 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67  } The [sqlite3_g
2f770 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d  et_auxdata(C,N)]
2f780 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2f790 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
2f7a0 20 20 20 20 20 20 20 20 20 74 6f 20 6d 65 74 61           to meta
2f7b0 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
2f7c0 77 69 74 68 20 74 68 65 20 4e 74 68 20 70 61 72  with the Nth par
2f7d0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51  ameter of the SQ
2f7e0 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  L function.**   
2f7f0 20 20 20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e         whose con
2f800 74 65 78 74 20 69 73 20 43 2c 20 6f 72 20 4e 55  text is C, or NU
2f810 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e  LL if there is n
2f820 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  o metadata assoc
2f830 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  iated.**        
2f840 20 20 77 69 74 68 20 74 68 61 74 20 70 61 72 61    with that para
2f850 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  meter..**.** {H1
2f860 36 32 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  6274} The [sqlit
2f870 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
2f880 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,N,P,D)] interfa
2f890 63 65 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74  ce assigns a met
2f8a0 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20  adata.**        
2f8b0 20 20 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74    pointer P to t
2f8c0 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72  he Nth parameter
2f8d0 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
2f8e0 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 78  tion with contex
2f8f0 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  t C..**.** {H162
2f900 37 36 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  76} SQLite will 
2f910 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
2f920 75 63 74 6f 72 20 44 20 77 69 74 68 20 61 20 73  uctor D with a s
2f930 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ingle argument.*
2f940 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 63 68  *          which
2f950 20 69 73 20 74 68 65 20 6d 65 74 61 64 61 74 61   is the metadata
2f960 20 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f   pointer P follo
2f970 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  wing a call to.*
2f980 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2f990 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2f9a0 43 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53  C,N,P,D)] when S
2f9b0 51 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20  QLite ceases to 
2f9c0 68 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  hold.**         
2f9d0 20 74 68 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a   the metadata..*
2f9e0 2a 0a 2a 2a 20 7b 48 31 36 32 37 37 7d 20 53 51  *.** {H16277} SQ
2f9f0 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68  Lite ceases to h
2fa00 6f 6c 64 20 6d 65 74 61 64 61 74 61 20 66 6f 72  old metadata for
2fa10 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
2fa20 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
2fa30 20 20 20 20 20 20 20 77 68 65 6e 20 74 68 65 20         when the 
2fa40 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 70 61  value of that pa
2fa50 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2e  rameter changes.
2fa60 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 38 7d 20  .**.** {H16278} 
2fa70 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65  When [sqlite3_se
2fa80 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
2fa90 44 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  D)] is invoked, 
2faa0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
2fab0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 63 61  *          is ca
2fac0 6c 6c 65 64 20 66 6f 72 20 61 6e 79 20 70 72 69  lled for any pri
2fad0 6f 72 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  or metadata asso
2fae0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2faf0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  same function.**
2fb00 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78            contex
2fb10 74 20 43 20 61 6e 64 20 70 61 72 61 6d 65 74 65  t C and paramete
2fb20 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  r N..**.** {H162
2fb30 37 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  79} SQLite will 
2fb40 63 61 6c 6c 20 64 65 73 74 72 75 63 74 6f 72 73  call destructors
2fb50 20 66 6f 72 20 61 6e 79 20 6d 65 74 61 64 61 74   for any metadat
2fb60 61 20 69 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a  a it is holding.
2fb70 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 61  **          in a
2fb80 20 70 61 72 74 69 63 75 6c 61 72 20 5b 70 72 65   particular [pre
2fb90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2fba0 20 53 20 77 68 65 6e 20 65 69 74 68 65 72 0a 2a   S when either.*
2fbb0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2fbc0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 6f 72  te3_reset(S)] or
2fbd0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2fbe0 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64  ze(S)] is called
2fbf0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
2fc00 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
2fc10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2fc20 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71   int N);.void sq
2fc30 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2fc40 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
2fc50 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a  t*, int N, void*
2fc60 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a  , void (*)(void*
2fc70 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ));.../*.** CAPI
2fc80 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20  3REF: Constants 
2fc90 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c  Defining Special
2fca0 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61   Destructor Beha
2fcb0 76 69 6f 72 20 7b 48 31 30 32 38 30 7d 20 3c 53  vior {H10280} <S
2fcc0 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30100>.**.** The
2fcd0 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
2fce0 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
2fcf0 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
2fd00 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
2fd10 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
2fd20 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
2fd30 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
2fd40 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49  sult_blob()].  I
2fd50 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
2fd60 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
2fd70 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
2fd80 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
2fd90 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
2fda0 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
2fdb0 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
2fdc0 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
2fdd0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
2fde0 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a  estroyed.  The.*
2fdf0 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  * SQLITE_TRANSIE
2fe00 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74  NT value means t
2fe10 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
2fe20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e  will likely chan
2fe30 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61  ge in.** the nea
2fe40 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61  r future and tha
2fe50 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20  t SQLite should 
2fe60 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69  make its own pri
2fe70 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  vate copy of.** 
2fe80 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f  the content befo
2fe90 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
2fea0 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20  .** The typedef 
2feb0 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20  is necessary to 
2fec0 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62  work around prob
2fed0 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a  lems in certain.
2fee0 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73  ** C++ compilers
2fef0 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32  .  See ticket #2
2ff00 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  191..*/.typedef 
2ff10 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64  void (*sqlite3_d
2ff20 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28  estructor_type)(
2ff30 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20  void*);.#define 
2ff40 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20  SQLITE_STATIC   
2ff50 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
2ff60 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a  tructor_type)0).
2ff70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
2ff80 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c  RANSIENT   ((sql
2ff90 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
2ffa0 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20  type)-1)../*.** 
2ffb0 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e  CAPI3REF: Settin
2ffc0 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20  g The Result Of 
2ffd0 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  An SQL Function 
2ffe0 7b 48 31 36 34 30 30 7d 20 3c 53 32 30 32 30 30  {H16400} <S20200
2fff0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
30000 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
30010 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
30020 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
30030 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
30040 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
30050 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
30060 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
30070 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30080 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
30090 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
300a0 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
300b0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
300c0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
300d0 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
300e0 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
300f0 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
30100 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
30110 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
30120 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
30130 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
30140 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
30150 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
30160 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
30170 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
30180 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
30190 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
301a0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
301b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
301c0 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  _blob() interfac
301d0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
301e0 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
301f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
30200 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
30210 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63  the BLOB whose c
30220 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65  ontent is pointe
30230 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73  d.** to by the s
30240 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
30250 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62  and which is N b
30260 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20  ytes long where 
30270 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  N is the.** thir
30280 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
30290 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
302a0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
302b0 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20   interfaces set 
302c0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
302d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
302e0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
302f0 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63  n to be a BLOB c
30300 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65  ontaining all ze
30310 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20  ro.** bytes and 
30320 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c  N bytes in size,
30330 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
30340 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64  value of the 2nd
30350 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
30360 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
30370 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e  sult_double() in
30380 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
30390 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
303a0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
303b0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
303c0 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67  to be a floating
303d0 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65   point value spe
303e0 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73  cified.** by its
303f0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
30400 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
30410 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
30420 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
30430 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
30440 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
30450 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
30460 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
30470 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
30480 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  on..** SQLite us
30490 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f  es the string po
304a0 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a  inted to by the.
304b0 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ** 2nd parameter
304c0 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75   of sqlite3_resu
304d0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
304e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
304f0 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65  or16().** as the
30500 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
30510 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69  r message.  SQLi
30520 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
30530 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
30540 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  ge string from s
30550 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
30560 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20  ror() as UTF-8. 
30570 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
30580 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
30590 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
305a0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
305b0 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
305c0 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
305d0 20 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70    If the third p
305e0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
305f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30600 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
30610 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
30620 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
30630 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
30640 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
30650 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
30660 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
30670 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
30680 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  cter..** If the 
30690 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
306a0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
306b0 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
306c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
306d0 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
306e0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
306f0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
30700 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
30710 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
30720 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
30730 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
30740 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54  or message..** T
30750 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
30760 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
30770 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30780 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
30790 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
307a0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
307b0 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
307c0 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
307d0 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
307e0 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
307f0 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
30800 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
30810 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
30820 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
30830 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65  out harm..** The
30840 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30850 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
30860 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
30870 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
30880 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
30890 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
308a0 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
308b0 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64 65  function.  By de
308c0 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72  fault,.** the er
308d0 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49  ror code is SQLI
308e0 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73 75 62  TE_ERROR.  A sub
308f0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
30900 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
30910 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
30920 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
30930 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
30940 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
30950 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
30960 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
30970 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69  esult_toobig() i
30980 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
30990 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
309a0 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
309b0 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
309c0 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
309d0 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  to long to repre
309e0 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  sent..**.** The 
309f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
30a00 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
30a10 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
30a20 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
30a30 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74  .** indicating t
30a40 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  hat a memory all
30a50 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
30a60 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
30a70 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
30a80 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
30a90 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
30aa0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
30ab0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
30ac0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
30ad0 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
30ae0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
30af0 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
30b00 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
30b10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30b20 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  int64() interfac
30b30 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
30b40 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
30b50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
30b60 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
30b70 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20  o be the 64-bit 
30b80 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
30b90 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
30ba0 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
30bb0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  t..**.** The sql
30bc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
30bd0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
30be0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
30bf0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
30c00 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
30c10 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
30c20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
30c30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
30c40 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
30c50 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a  esult_text16(),.
30c60 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
30c70 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e  t_text16le(), an
30c80 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
30c90 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65  _text16be() inte
30ca0 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68  rfaces.** set th
30cb0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
30cc0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
30cd0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
30ce0 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65  on to be.** a te
30cf0 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20  xt string which 
30d00 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
30d10 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20  s UTF-8, UTF-16 
30d20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
30d30 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  r,.** UTF-16 lit
30d40 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle endian, or U
30d50 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e  TF-16 big endian
30d60 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
30d70 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  ** SQLite takes 
30d80 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20  the text result 
30d90 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61  from the applica
30da0 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  tion from.** the
30db0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
30dc0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  f the sqlite3_re
30dd0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
30de0 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65  faces..** If the
30df0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
30e00 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
30e10 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
30e20 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61  faces.** is nega
30e30 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74  tive, then SQLit
30e40 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74  e takes result t
30e50 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  ext from the 2nd
30e60 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68   parameter.** th
30e70 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
30e80 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
30e90 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
30ea0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
30eb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
30ec0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
30ed0 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
30ee0 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
30ef0 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
30f00 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
30f10 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
30f20 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
30f30 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
30f40 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
30f50 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
30f60 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a  nction result..*
30f70 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72  * If the 4th par
30f80 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
30f90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
30fa0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
30fb0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
30fc0 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e  lt_blob is a non
30fd0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
30fe0 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73  hen SQLite calls
30ff0 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f   that.** functio
31000 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63  n as the destruc
31010 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20  tor on the text 
31020 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77  or BLOB result w
31030 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69  hen it has.** fi
31040 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
31050 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20  t result..** If 
31060 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
31070 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
31080 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
31090 74 65 72 66 61 63 65 73 20 6f 72 0a 2a 2a 20 73  terfaces or.** s
310a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
310b0 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
310c0 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
310d0 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53  E_STATIC, then S
310e0 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73  QLite.** assumes
310f0 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f   that the text o
31100 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73  r BLOB result is
31110 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61   in constant spa
31120 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a  ce and does not.
31130 2a 2a 20 63 6f 70 79 20 74 68 65 20 69 74 20 6f  ** copy the it o
31140 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
31150 74 6f 72 20 77 68 65 6e 20 69 74 20 68 61 73 20  tor when it has 
31160 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
31170 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  hat result..** I
31180 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
31190 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
311a0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
311b0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
311c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
311d0 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
311e0 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
311f0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
31200 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
31210 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
31220 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
31230 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
31240 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
31250 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
31260 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
31270 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
31280 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
31290 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
312a0 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
312b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
312c0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
312d0 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
312e0 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
312f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
31300 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
31310 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
31320 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20  ameter.  The.** 
31330 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
31340 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
31350 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
31360 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
31370 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
31380 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
31390 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e  ue] specified in
313a0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d   the parameter m
313b0 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  ay change or.** 
313c0 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61  be deallocated a
313d0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73  fter sqlite3_res
313e0 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75  ult_value() retu
313f0 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d  rns without harm
31400 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74 65  ..** A [protecte
31410 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
31420 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61   object may alwa
31430 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65  ys be used where
31440 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
31450 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
31460 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71  e] object is req
31470 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72  uired, so either
31480 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c  .** kind of [sql
31490 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
314a0 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77  ct can be used w
314b0 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61  ith this interfa
314c0 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ce..**.** If the
314d0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
314e0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68  called from with
314f0 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74  in the different
31500 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20   thread.** than 
31510 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69  the one containi
31520 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ng the applicati
31530 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
31540 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65  ion that receive
31550 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  d.** the [sqlite
31560 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74  3_context] point
31570 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  er, the results 
31580 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
31590 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
315a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 33 7d 20  .**.** {H16403} 
315b0 54 68 65 20 64 65 66 61 75 6c 74 20 72 65 74 75  The default retu
315c0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e  rn value from an
315d0 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  y SQL function i
315e0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  s NULL..**.** {H
315f0 31 36 34 30 36 7d 20 54 68 65 20 5b 73 71 6c 69  16406} The [sqli
31600 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
31610 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
31620 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
31630 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
31640 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
31650 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 20 42  tion C to be a B
31660 4c 4f 42 20 74 68 61 74 20 69 73 20 4e 20 62 79  LOB that is N by
31670 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tes.**          
31680 69 6e 20 6c 65 6e 67 74 68 20 61 6e 64 20 77 69  in length and wi
31690 74 68 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  th content point
316a0 65 64 20 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a  ed to by V..**.*
316b0 2a 20 7b 48 31 36 34 30 39 7d 20 54 68 65 20 5b  * {H16409} The [
316c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
316d0 6f 75 62 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65  ouble(C,V)] inte
316e0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
316f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
31700 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
31710 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
31720 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
31730 74 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a  t value V..**.**
31740 20 7b 48 31 36 34 31 32 7d 20 54 68 65 20 5b 73   {H16412} The [s
31750 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31760 72 6f 72 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65  ror(C,V,N)] inte
31770 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
31780 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
31790 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75       value of fu
317a0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
317b0 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68  n exception with
317c0 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20   error code.**  
317d0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
317e0 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46  ERROR] and a UTF
317f0 2d 38 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  -8 error message
31800 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75   copied from V u
31810 70 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  p to the.**     
31820 20 20 20 20 20 66 69 72 73 74 20 7a 65 72 6f 20       first zero 
31830 62 79 74 65 20 6f 72 20 75 6e 74 69 6c 20 4e 20  byte or until N 
31840 62 79 74 65 73 20 61 72 65 20 72 65 61 64 20 69  bytes are read i
31850 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e  f N is positive.
31860 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 35 7d 20  .**.** {H16415} 
31870 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
31880 75 6c 74 5f 65 72 72 6f 72 31 36 28 43 2c 56 2c  ult_error16(C,V,
31890 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  N)] interface ch
318a0 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
318b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
318c0 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
318d0 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74   to be an except
318e0 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63  ion with error c
318f0 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
31900 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61  [SQLITE_ERROR] a
31910 6e 64 20 61 20 55 54 46 2d 31 36 20 6e 61 74 69  nd a UTF-16 nati
31920 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 65 72  ve byte order er
31930 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20  ror message.**  
31940 20 20 20 20 20 20 20 20 63 6f 70 69 65 64 20 66          copied f
31950 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65 20  rom V up to the 
31960 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
31970 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69 6c 20 4e  nator or until N
31980 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20   bytes.**       
31990 20 20 20 61 72 65 20 72 65 61 64 20 69 66 20 4e     are read if N
319a0 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a   is positive..**
319b0 0a 2a 2a 20 7b 48 31 36 34 31 38 7d 20 54 68 65  .** {H16418} The
319c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
319d0 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 43 29  _error_toobig(C)
319e0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
319f0 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
31a00 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
31a10 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
31a20 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
31a30 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
31a40 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
31a50 20 20 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47    [SQLITE_TOOBIG
31a60 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72  ] and an appropr
31a70 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61  iate error messa
31a80 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32  ge..**.** {H1642
31a90 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
31aa0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
31ab0 65 6d 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  em(C)] interface
31ac0 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
31ad0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
31ae0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e  value of the fun
31af0 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
31b00 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
31b10 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
31b20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4e         [SQLITE_N
31b30 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70  OMEM] and an app
31b40 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d  ropriate error m
31b50 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  essage..**.** {H
31b60 31 36 34 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  16424} The [sqli
31b70 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31b80 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69 6e 74 65  _code(C,E)] inte
31b90 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
31ba0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
31bb0 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
31bc0 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  e function C to 
31bd0 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
31be0 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 20  with error code 
31bf0 45 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 54  E..**          T
31c00 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
31c10 20 74 65 78 74 20 69 73 20 75 6e 63 68 61 6e 67   text is unchang
31c20 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32  ed..**.** {H1642
31c30 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
31c40 72 65 73 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d  result_int(C,V)]
31c50 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
31c60 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
31c70 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
31c80 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
31c90 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 69   be the 32-bit i
31ca0 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a  nteger value V..
31cb0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 30 7d 20 54  **.** {H16430} T
31cc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
31cd0 6c 74 5f 69 6e 74 36 34 28 43 2c 56 29 5d 20 69  lt_int64(C,V)] i
31ce0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
31cf0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
31d00 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
31d10 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
31d20 65 20 74 68 65 20 36 34 2d 62 69 74 20 69 6e 74  e the 64-bit int
31d30 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a  eger value V..**
31d40 0a 2a 2a 20 7b 48 31 36 34 33 33 7d 20 54 68 65  .** {H16433} The
31d50 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
31d60 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66  _null(C)] interf
31d70 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
31d80 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
31d90 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
31da0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 4e 55 4c  tion C to be NUL
31db0 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 36  L..**.** {H16436
31dc0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
31dd0 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e  esult_text(C,V,N
31de0 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
31df0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
31e00 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
31e10 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
31e20 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d  C to be the UTF-
31e30 38 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20  8 string.**     
31e40 20 20 20 20 20 56 20 75 70 20 74 6f 20 74 68 65       V up to the
31e50 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
31e60 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20   is negative.** 
31e70 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
31e80 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66  first N bytes of
31e90 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e   V if N is non-n
31ea0 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
31eb0 48 31 36 34 33 39 7d 20 54 68 65 20 5b 73 71 6c  H16439} The [sql
31ec0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31ed0 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74  16(C,V,N,D)] int
31ee0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
31ef0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
31f00 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
31f10 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
31f20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76  the UTF-16 nativ
31f30 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
31f40 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
31f50 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
31f60 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e  t zero if N is n
31f70 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20  egative.**      
31f80 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74      or the first
31f90 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66   N bytes of V if
31fa0 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
31fb0 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34  ve..**.** {H1644
31fc0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
31fd0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
31fe0 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
31ff0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
32000 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
32010 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
32020 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
32030 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69   UTF-16 big-endi
32040 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  an.**          s
32050 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68  tring V up to th
32060 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20  e first zero if 
32070 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  N is negative.**
32080 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65            or the
32090 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f   first N bytes o
320a0 72 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d  r V if N is non-
320b0 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
320c0 7b 48 31 36 34 34 35 7d 20 54 68 65 20 5b 73 71  {H16445} The [sq
320d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
320e0 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16le(C,V,N,D)] 
320f0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
32100 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
32110 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
32120 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
32130 62 65 20 74 68 65 20 55 54 46 2d 31 36 20 6c 69  be the UTF-16 li
32140 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20  ttle-endian.**  
32150 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56          string V
32160 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
32170 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65   zero if N is ne
32180 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  gative.**       
32190 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20     or the first 
321a0 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20  N bytes of V if 
321b0 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  N is non-negativ
321c0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 38  e..**.** {H16448
321d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
321e0 65 73 75 6c 74 5f 76 61 6c 75 65 28 43 2c 56 29  esult_value(C,V)
321f0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
32200 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
32210 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
32220 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
32230 6f 20 62 65 20 74 68 65 20 5b 75 6e 70 72 6f 74  o be the [unprot
32240 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32250 6c 75 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  lue].**         
32260 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a   object V..**.**
32270 20 7b 48 31 36 34 35 31 7d 20 54 68 65 20 5b 73   {H16451} The [s
32280 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
32290 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74  roblob(C,N)] int
322a0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
322b0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
322c0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
322d0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
322e0 61 6e 20 4e 2d 62 79 74 65 20 42 4c 4f 42 20 6f  an N-byte BLOB o
322f0 66 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a  f all zeros..**.
32300 2a 2a 20 7b 48 31 36 34 35 34 7d 20 54 68 65 20  ** {H16454} The 
32310 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32320 65 72 72 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71  error()] and [sq
32330 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32340 6f 72 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20  or16()].**      
32350 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 6d      interfaces m
32360 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ake a copy of th
32370 65 69 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67  eir error messag
32380 65 20 73 74 72 69 6e 67 73 20 62 65 66 6f 72 65  e strings before
32390 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
323a0 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  urning..**.** {H
323b0 31 36 34 35 37 7d 20 49 66 20 74 68 65 20 44 20  16457} If the D 
323c0 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d  destructor param
323d0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
323e0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56  _result_blob(C,V
323f0 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
32400 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
32410 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44  ult_text(C,V,N,D
32420 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  )], [sqlite3_res
32430 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e  ult_text16(C,V,N
32440 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
32450 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
32460 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e  t_text16be(C,V,N
32470 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
32480 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
32490 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c  sult_text16le(C,
324a0 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63  V,N,D)] is the c
324b0 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f  onstant [SQLITE_
324c0 53 54 41 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20  STATIC].**      
324d0 20 20 20 20 74 68 65 6e 20 6e 6f 20 64 65 73 74      then no dest
324e0 72 75 63 74 6f 72 20 69 73 20 65 76 65 72 20 63  ructor is ever c
324f0 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 70 6f 69  alled on the poi
32500 6e 74 65 72 20 56 20 61 6e 64 20 53 51 4c 69 74  nter V and SQLit
32510 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  e.**          as
32520 73 75 6d 65 73 20 74 68 61 74 20 56 20 69 73 20  sumes that V is 
32530 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  immutable..**.**
32540 20 7b 48 31 36 34 36 30 7d 20 49 66 20 74 68 65   {H16460} If the
32550 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61   D destructor pa
32560 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
32570 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
32580 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
32590 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
325a0 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c  result_text(C,V,
325b0 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  N,D)], [sqlite3_
325c0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c  result_text16(C,
325d0 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
325e0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
325f0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c  sult_text16be(C,
32600 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,N,D)], or.**  
32610 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
32620 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
32630 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68  (C,V,N,D)] is th
32640 65 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20  e constant.**   
32650 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54         [SQLITE_T
32660 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 74  RANSIENT] then t
32670 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  he interfaces ma
32680 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
32690 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
326a0 6e 74 65 6e 74 20 6f 66 20 56 20 61 6e 64 20 72  ntent of V and r
326b0 65 74 61 69 6e 73 20 74 68 65 20 63 6f 70 79 2e  etains the copy.
326c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 33 7d 20  .**.** {H16463} 
326d0 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63  If the D destruc
326e0 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f  tor parameter to
326f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
32700 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _blob(C,V,N,D)],
32710 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
32720 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32730 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71  t(C,V,N,D)], [sq
32740 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32750 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  t16(C,V,N,D)],.*
32760 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
32770 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
32780 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f  6be(C,V,N,D)], o
32790 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
327a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
327b0 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d  xt16le(C,V,N,D)]
327c0 20 69 73 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f   is some value o
327d0 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20  ther than.**    
327e0 20 20 20 20 20 20 74 68 65 20 63 6f 6e 73 74 61        the consta
327f0 6e 74 73 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  nts [SQLITE_STAT
32800 49 43 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  IC] and [SQLITE_
32810 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 0a  TRANSIENT] then.
32820 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69  **          SQLi
32830 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
32840 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20  he destructor D 
32850 77 69 74 68 20 56 20 61 73 20 69 74 73 20 6f 6e  with V as its on
32860 6c 79 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20  ly argument.**  
32870 20 20 20 20 20 20 20 20 77 68 65 6e 20 69 74 20          when it 
32880 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
32890 68 20 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a  h the V value..*
328a0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
328b0 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
328c0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
328d0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
328e0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
328f0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32900 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
32910 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
32920 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
32930 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
32940 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32950 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
32960 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
32970 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
32980 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32990 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
329a0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
329b0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
329c0 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
329d0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
329e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
329f0 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
32a00 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
32a10 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
32a20 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
32a30 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
32a40 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
32a50 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
32a60 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
32a70 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
32a80 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
32a90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32aa0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
32ab0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32ac0 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
32ad0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
32ae0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32af0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
32b00 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
32b10 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
32b20 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
32b30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32b40 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
32b50 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
32b60 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
32b70 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
32b80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32b90 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
32ba0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
32bb0 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
32bc0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
32bd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
32be0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
32bf0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
32c00 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
32c10 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
32c20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32c30 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
32c40 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
32c50 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
32c60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
32c70 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
32c80 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
32c90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32ca0 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
32cb0 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20  ating Sequences 
32cc0 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 33 30 30  {H16600} <S20300
32cd0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  >.**.** These fu
32ce0 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64  nctions are used
32cf0 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c   to add new coll
32d00 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
32d10 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  to the.** [datab
32d20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
32d30 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
32d40 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
32d50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  .**.** The name 
32d60 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61  of the new colla
32d70 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
32d80 20 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20   specified as a 
32d90 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
32da0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
32db0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
32dc0 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
32dd0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
32de0 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
32df0 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69   string for sqli
32e00 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
32e10 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c  tion16(). In all
32e20 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61   cases.** the na
32e30 6d 65 20 69 73 20 70 61 73 73 65 64 20 61 73 20  me is passed as 
32e40 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
32e50 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
32e60 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72  .** The third ar
32e70 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e  gument may be on
32e80 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e  e of the constan
32e90 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ts [SQLITE_UTF8]
32ea0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  ,.** [SQLITE_UTF
32eb0 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45  16LE] or [SQLITE
32ec0 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63  _UTF16BE], indic
32ed0 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 75  ating that the u
32ee0 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ser-supplied.** 
32ef0 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20  routine expects 
32f00 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69  to be passed poi
32f10 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
32f20 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
32f30 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  TF-8,.** UTF-16 
32f40 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f  little-endian, o
32f50 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64  r UTF-16 big-end
32f60 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
32f70 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  y. The.** third 
32f80 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61  argument might a
32f90 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55  lso be [SQLITE_U
32fa0 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f  TF16_ALIGNED] to
32fb0 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 0a 2a   indicate that.*
32fc0 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78  * the routine ex
32fd0 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74  pects pointers t
32fe0 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c  o 16-bit word al
32ff0 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  igned strings.**
33000 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68   of UTF-16 in th
33010 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
33020 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
33030 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  computer..**.** 
33040 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
33050 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72   user supplied r
33060 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70  outine must be p
33070 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66  assed as the fif
33080 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  th.** argument. 
33090 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20   If it is NULL, 
330a0 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65  this is the same
330b0 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65   as deleting the
330c0 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
330d0 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20  quence (so that 
330e0 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61  SQLite cannot ca
330f0 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a  ll it anymore)..
33100 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68 65  ** Each time the
33110 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70   application sup
33120 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  plied function i
33130 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73  s invoked, it is
33140 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74   passed.** as it
33150 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
33160 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  r a copy of the 
33170 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 20  void* passed as 
33180 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
33190 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
331a0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
331b0 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  on() or sqlite3_
331c0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
331d0 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  16()..**.** The 
331e0 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65  remaining argume
331f0 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69  nts to the appli
33200 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20  cation-supplied 
33210 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20  routine are two 
33220 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68  strings,.** each
33230 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
33240 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29  a (length, data)
33250 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65   pair and encode
33260 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e  d in the encodin
33270 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61  g.** that was pa
33280 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
33290 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20  d argument when 
332a0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  the collation se
332b0 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65  quence was.** re
332c0 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20  gistered. {END} 
332d0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
332e0 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69   defined collati
332f0 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  on routine shoul
33300 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61  d.** return nega
33310 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f  tive, zero or po
33320 73 69 74 69 76 65 20 69 66 20 74 68 65 20 66 69  sitive if the fi
33330 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65  rst string is le
33340 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61  ss than,.** equa
33350 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
33360 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
33370 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53   string. i.e. (S
33380 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32  TRING1 - STRING2
33390 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
333a0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
333b0 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73  ation_v2() works
333c0 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72   like sqlite3_cr
333d0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
333e0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
333f0 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72  it takes an extr
33400 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  a argument which
33410 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
33420 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c   for.** the coll
33430 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74  ation.  The dest
33440 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
33450 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   when the collat
33460 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f  ion is.** destro
33470 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65  yed and is passe
33480 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  d a copy of the 
33490 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
334a0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a   void* pointer.*
334b0 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
334c0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
334d0 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61  n_v2()..** Colla
334e0 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f  tions are destro
334f0 79 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72  yed when they ar
33500 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
33510 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74  later calls to t
33520 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20  he.** collation 
33530 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  creation functio
33540 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b  ns or when the [
33550 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33560 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a  ion] is closed.*
33570 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
33580 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
33590 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
335a0 2a 2a 20 7b 48 31 36 36 30 33 7d 20 41 20 73 75  ** {H16603} A su
335b0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
335c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
335d0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
335e0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
335f0 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e 74 65  X,E,P,F,D)] inte
33600 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20  rface.**        
33610 20 20 72 65 67 69 73 74 65 72 73 20 66 75 6e 63    registers func
33620 74 69 6f 6e 20 46 20 61 73 20 74 68 65 20 63 6f  tion F as the co
33630 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f  mparison functio
33640 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20  n used to.**    
33650 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74 20        implement 
33660 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 74  collation X on t
33670 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
33680 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a  nection] B for.*
33690 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
336a0 61 73 65 73 20 68 61 76 69 6e 67 20 65 6e 63 6f  ases having enco
336b0 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ding E..**.** {H
336c0 31 36 36 30 34 7d 20 53 51 4c 69 74 65 20 75 6e  16604} SQLite un
336d0 64 65 72 73 74 61 6e 64 73 20 74 68 65 20 58 20  derstands the X 
336e0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
336f0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
33700 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33710 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
33720 44 29 5d 20 61 73 20 61 20 7a 65 72 6f 2d 74 65  D)] as a zero-te
33730 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20  rminated.**     
33740 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e       UTF-8 strin
33750 67 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  g in which case 
33760 69 73 20 69 67 6e 6f 72 65 64 20 66 6f 72 20 41  is ignored for A
33770 53 43 49 49 20 63 68 61 72 61 63 74 65 72 73 20  SCII characters 
33780 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
33790 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74 20 66  is significant f
337a0 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61  or non-ASCII cha
337b0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b  racters..**.** {
337c0 48 31 36 36 30 36 7d 20 53 75 63 63 65 73 73 69  H16606} Successi
337d0 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ve calls to [sql
337e0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
337f0 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
33800 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,F,D)].**       
33810 20 20 20 77 69 74 68 20 74 68 65 20 73 61 6d 65     with the same
33820 20 76 61 6c 75 65 73 20 66 6f 72 20 42 2c 20 58   values for B, X
33830 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72 72 69 64  , and E, overrid
33840 65 20 70 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a  e prior values.*
33850 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 50 2c  *          of P,
33860 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a   F, and D..**.**
33870 20 7b 48 31 36 36 30 39 7d 20 49 66 20 74 68 65   {H16609} If the
33880 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 69 6e   destructor D in
33890 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
338a0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
338b0 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20  X,E,P,F,D)].**  
338c0 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74 20 4e          is not N
338d0 55 4c 4c 20 74 68 65 6e 20 69 74 20 69 73 20 63  ULL then it is c
338e0 61 6c 6c 65 64 20 77 69 74 68 20 61 72 67 75 6d  alled with argum
338f0 65 6e 74 20 50 20 77 68 65 6e 20 74 68 65 0a 2a  ent P when the.*
33900 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
33910 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
33920 20 64 72 6f 70 70 65 64 20 62 79 20 53 51 4c 69   dropped by SQLi
33930 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31  te..**.** {H1661
33940 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66  2} A collating f
33950 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70  unction is dropp
33960 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 6f 76  ed when it is ov
33970 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  erloaded..**.** 
33980 7b 48 31 36 36 31 35 7d 20 41 20 63 6f 6c 6c 61  {H16615} A colla
33990 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
339a0 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20 74 68   dropped when th
339b0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
339c0 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
339d0 20 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e    is closed usin
339e0 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  g [sqlite3_close
339f0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  ()]..**.** {H166
33a00 31 38 7d 20 54 68 65 20 70 6f 69 6e 74 65 72 20  18} The pointer 
33a10 50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72  P in [sqlite3_cr
33a20 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
33a30 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a  2(B,X,E,P,F,D)].
33a40 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 70  **          is p
33a50 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
33a60 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
33a70 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6d 70  eter to the comp
33a80 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  arison.**       
33a90 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f     function F fo
33aa0 72 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  r all subsequent
33ab0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
33ac0 46 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 31  F..**.** {H16621
33ad0 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  } A call to [sql
33ae0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33af0 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29  ation(B,X,E,P,F)
33b00 5d 20 69 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20  ] is exactly.** 
33b10 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d           the sam
33b20 65 20 61 73 20 61 20 63 61 6c 6c 20 74 6f 20 5b  e as a call to [
33b30 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
33b40 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 20 77  ollation_v2()] w
33b50 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
33b60 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74  the same paramet
33b70 65 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64  ers and a NULL d
33b80 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a  estructor..**.**
33b90 20 7b 48 31 36 36 32 34 7d 20 46 6f 6c 6c 6f 77   {H16624} Follow
33ba0 69 6e 67 20 61 20 5b 73 71 6c 69 74 65 33 5f 63  ing a [sqlite3_c
33bb0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
33bc0 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
33bd0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  ,.**          SQ
33be0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 63 6f  Lite uses the co
33bf0 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f  mparison functio
33c00 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74 65 78 74  n F for all text
33c10 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20   comparison.**  
33c20 20 20 20 20 20 20 20 20 6f 70 65 72 61 74 69 6f          operatio
33c30 6e 73 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ns on the [datab
33c40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
33c50 42 20 6f 6e 20 74 65 78 74 20 76 61 6c 75 65 73  B on text values
33c60 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
33c70 20 20 75 73 65 20 74 68 65 20 63 6f 6c 6c 61 74    use the collat
33c80 69 6e 67 20 73 65 71 75 65 6e 63 65 20 6e 61 6d  ing sequence nam
33c90 65 64 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ed X..**.** {H16
33ca0 36 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  627} The [sqlite
33cb0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33cc0 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d  on16(B,X,E,P,F)]
33cd0 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 0a   works the same.
33ce0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 5b  **          as [
33cf0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
33d00 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50  ollation(B,X,E,P
33d10 2c 46 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  ,F)] except that
33d20 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
33d30 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20   collation name 
33d40 58 20 69 73 20 75 6e 64 65 72 73 74 6f 6f 64 20  X is understood 
33d50 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
33d60 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a  ive byte order.*
33d70 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 74 65  *          inste
33d80 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a  ad of UTF-8..**.
33d90 2a 2a 20 7b 48 31 36 36 33 30 7d 20 57 68 65 6e  ** {H16630} When
33da0 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72   multiple compar
33db0 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61  ison functions a
33dc0 72 65 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72  re available for
33dd0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20   the same.**    
33de0 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20        collating 
33df0 73 65 71 75 65 6e 63 65 2c 20 53 51 4c 69 74 65  sequence, SQLite
33e00 20 63 68 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65   chooses the one
33e10 20 77 68 6f 73 65 20 74 65 78 74 20 65 6e 63 6f   whose text enco
33e20 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ding.**         
33e30 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65   requires the le
33e40 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f  ast amount of co
33e50 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68  nversion from th
33e60 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20  e default.**    
33e70 20 20 20 20 20 20 74 65 78 74 20 65 6e 63 6f 64        text encod
33e80 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62  ing of the datab
33e90 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ase..*/.int sqli
33ea0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33eb0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  tion(.  sqlite3*
33ec0 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
33ed0 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
33ee0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
33ef0 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
33f00 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
33f10 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
33f20 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
33f30 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
33f40 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
33f50 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
33f60 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
33f70 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
33f80 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
33f90 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
33fa0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
33fb0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
33fc0 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
33fd0 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
33fe0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
33ff0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
34000 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
34010 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d  const void *zNam
34020 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  e,.  int eTextRe
34030 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
34040 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
34050 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
34060 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
34070 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
34080 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69  API3REF: Collati
34090 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61  on Needed Callba
340a0 63 6b 73 20 7b 48 31 36 37 30 30 7d 20 3c 53 32  cks {H16700} <S2
340b0 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61  0300>.**.** To a
340c0 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
340d0 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
340e0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
340f0 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
34100 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
34110 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
34120 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
34130 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
34140 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
34150 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
34160 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68   to be called wh
34170 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
34180 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  ned collation.**
34190 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71   sequence is req
341a0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  uired..**.** If 
341b0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
341c0 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
341d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
341e0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
341f0 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  API,.** then it 
34200 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61  is passed the na
34210 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64  mes of undefined
34220 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
34230 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a  nces as strings.
34240 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  ** encoded in UT
34250 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d 20 49 66  F-8. {H16703} If
34260 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
34270 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
34280 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61   used,.** the na
34290 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61  mes are passed a
342a0 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
342b0 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
342c0 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c  order..** A call
342d0 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74   to either funct
342e0 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79  ion replaces any
342f0 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61   existing callba
34300 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ck..**.** When t
34310 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
34320 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
34330 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
34340 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
34350 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
34360 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
34370 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
34380 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
34390 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
343a0 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
343b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
343c0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
343d0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
343e0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
343f0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
34400 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
34410 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
34420 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
34430 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
34440 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
34450 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
34460 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
34470 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
34480 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
34490 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
344a0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
344b0 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
344c0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a  tion sequence..*
344d0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
344e0 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
344f0 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
34500 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
34510 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
34520 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34530 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
34540 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34550 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
34560 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34570 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
34580 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
34590 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 32 7d 20  .**.** {H16702} 
345a0 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
345b0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
345c0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44  llation_needed(D
345d0 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,P,F)].**       
345e0 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63     or [sqlite3_c
345f0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
34600 36 28 44 2c 50 2c 46 29 5d 20 63 61 75 73 65 73  6(D,P,F)] causes
34610 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
34620 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
34630 63 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f  ction] D to invo
34640 6b 65 20 63 61 6c 6c 62 61 63 6b 20 46 20 77 69  ke callback F wi
34650 74 68 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20  th first.**     
34660 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 50       parameter P
34670 20 77 68 65 6e 65 76 65 72 20 69 74 20 6e 65 65   whenever it nee
34680 64 73 20 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20  ds a comparison 
34690 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a  function for a.*
346a0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
346b0 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 74 68  ting sequence th
346c0 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b  at it does not k
346d0 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a  now about..**.**
346e0 20 7b 48 31 36 37 30 34 7d 20 45 61 63 68 20 73   {H16704} Each s
346f0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
34700 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  o [sqlite3_colla
34710 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f  tion_needed()] o
34720 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
34730 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
34740 5f 6e 65 65 64 65 64 31 36 28 29 5d 20 6f 76 65  _needed16()] ove
34750 72 72 69 64 65 73 20 74 68 65 20 63 61 6c 6c 62  rrides the callb
34760 61 63 6b 20 72 65 67 69 73 74 65 72 65 64 0a 2a  ack registered.*
34770 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68  *          on th
34780 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
34790 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20   connection] by 
347a0 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65  prior calls to e
347b0 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
347c0 20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a    interface..**.
347d0 2a 2a 20 7b 48 31 36 37 30 36 7d 20 54 68 65 20  ** {H16706} The 
347e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 72 65 71 75  name of the requ
347f0 65 73 74 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20  ested collating 
34800 66 75 6e 63 74 69 6f 6e 20 70 61 73 73 65 64 20  function passed 
34810 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
34820 20 20 20 34 74 68 20 70 61 72 61 6d 65 74 65 72     4th parameter
34830 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
34840 20 69 73 20 69 6e 20 55 54 46 2d 38 20 69 66 20   is in UTF-8 if 
34850 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
34860 20 20 20 20 20 20 20 20 20 77 61 73 20 72 65 67           was reg
34870 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73  istered using [s
34880 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
34890 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a  _needed()] and.*
348a0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e  *          is in
348b0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
348c0 79 74 65 20 6f 72 64 65 72 20 69 66 20 74 68 65  yte order if the
348d0 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a   callback was.**
348e0 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
348f0 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ered using [sqli
34900 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
34910 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e  eded16()]..*/.in
34920 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
34930 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71  ion_needed(.  sq
34940 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
34950 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
34960 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
34970 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63  eTextRep,const c
34980 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  har*).);.int sql
34990 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
349a0 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74  eeded16(.  sqlit
349b0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  e3*, .  void*,. 
349c0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
349d0 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
349e0 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  tRep,const void*
349f0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63  ).);../*.** Spec
34a00 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20  ify the key for 
34a10 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74  an encrypted dat
34a20 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75  abase.  This rou
34a30 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  tine should be.*
34a40 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61  * called right a
34a50 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  fter sqlite3_ope
34a60 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n()..**.** The c
34a70 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
34a80 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
34a90 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
34aa0 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
34ab0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
34ac0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  /.int sqlite3_ke
34ad0 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
34ae0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
34af0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
34b00 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
34b10 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
34b20 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
34b30 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a    /* The key */.
34b40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65  );../*.** Change
34b50 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f   the key on an o
34b60 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49  pen database.  I
34b70 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  f the current da
34b80 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a  tabase is not.**
34b90 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73   encrypted, this
34ba0 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e   routine will en
34bb0 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e  crypt it.  If pN
34bc0 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30  ew==0 or nNew==0
34bd0 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  , the.** databas
34be0 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a  e is decrypted..
34bf0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
34c00 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
34c10 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
34c20 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
34c30 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
34c40 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
34c50 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a   sqlite3_rekey(.
34c60 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
34c70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34c80 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
34c90 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
34ca0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
34cb0 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
34cc0 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f  * The new key */
34cd0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
34ce0 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65  REF: Suspend Exe
34cf0 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f  cution For A Sho
34d00 72 74 20 54 69 6d 65 20 7b 48 31 30 35 33 30 7d  rt Time {H10530}
34d10 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S40410>.**.** 
34d20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
34d30 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  p() function cau
34d40 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
34d50 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
34d60 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
34d70 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
34d80 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
34d90 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
34da0 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
34db0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  .**.** If the op
34dc0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64  erating system d
34dd0 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20  oes not support 
34de0 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77  sleep requests w
34df0 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f  ith.** milliseco
34e00 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69  nd time resoluti
34e10 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d  on, then the tim
34e20 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65  e will be rounde
34e30 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e  d up to.** the n
34e40 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54  earest second. T
34e50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
34e60 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
34e70 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72  ep actually.** r
34e80 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
34e90 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
34ea0 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
34eb0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
34ec0 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
34ed0 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
34ee0 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
34ef0 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
34f00 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
34f10 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
34f20 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
34f30 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 33 7d 20 54  **.** {H10533} T
34f40 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65  he [sqlite3_slee
34f50 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20  p(M)] interface 
34f60 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 6c 65  invokes the xSle
34f70 65 70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  ep.**          m
34f80 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
34f90 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
34fa0 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20  s|VFS] in order 
34fb0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  to.**          s
34fc0 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
34fd0 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   of the current 
34fe0 74 68 72 65 61 64 20 66 6f 72 20 61 74 20 6c 65  thread for at le
34ff0 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ast.**          
35000 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a  M milliseconds..
35010 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 36 7d 20 54  **.** {H10536} T
35020 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65  he [sqlite3_slee
35030 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20  p(M)] interface 
35040 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
35050 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  er of.**        
35060 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f    milliseconds o
35070 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
35080 20 72 65 71 75 65 73 74 65 64 20 6f 66 20 74 68   requested of th
35090 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20  e operating.**  
350a0 20 20 20 20 20 20 20 20 73 79 73 74 65 6d 2c 20          system, 
350b0 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6c  which might be l
350c0 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 70  arger than the p
350d0 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69  arameter M..*/.i
350e0 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  nt sqlite3_sleep
350f0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
35100 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
35110 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69  The Folder Holdi
35120 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c  ng Temporary Fil
35130 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53 32 30  es {H10310} <S20
35140 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  000>.**.** If th
35150 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  is global variab
35160 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  le is made to po
35170 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
35180 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20  which is.** the 
35190 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72  name of a folder
351a0 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f   (a.k.a. directo
351b0 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65  ry), then all te
351c0 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a  mporary files.**
351d0 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69   created by SQLi
351e0 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65  te will be place
351f0 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74  d in that direct
35200 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61  ory.  If this va
35210 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e  riable.** is a N
35220 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
35230 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d  n SQLite perform
35240 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61  s a search for a
35250 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a  n appropriate.**
35260 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20   temporary file 
35270 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
35280 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
35290 74 6f 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  to modify this v
352a0 61 72 69 61 62 6c 65 20 6f 6e 63 65 20 61 20 5b  ariable once a [
352b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
352c0 69 6f 6e 5d 0a 2a 2a 20 68 61 73 20 62 65 65 6e  ion].** has been
352d0 20 6f 70 65 6e 65 64 2e 20 20 49 74 20 69 73 20   opened.  It is 
352e0 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68  intended that th
352f0 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73  is variable be s
35300 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61  et once.** as pa
35310 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e  rt of process in
35320 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
35330 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69   before any SQLi
35340 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  te interface.** 
35350 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65  routines have be
35360 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65 6d 61  en call and rema
35370 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 74 68 65  in unchanged the
35380 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49  reafter..*/.SQLI
35390 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a  TE_EXTERN char *
353a0 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
353b0 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ectory;../*.** C
353c0 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f  API3REF: Test Fo
353d0 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f  r Auto-Commit Mo
353e0 64 65 20 7b 48 31 32 39 33 30 7d 20 3c 53 36 30  de {H12930} <S60
353f0 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  200>.** KEYWORDS
35400 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  : {autocommit mo
35410 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  de}.**.** The sq
35420 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
35430 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  mmit() interface
35440 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
35450 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  o or.** zero if 
35460 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61  the given databa
35470 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
35480 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75   or is not in au
35490 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a  tocommit mode,.*
354a0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
354b0 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
354c0 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c   is on by defaul
354d0 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74  t..** Autocommit
354e0 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65   mode is disable
354f0 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73  d by a [BEGIN] s
35500 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74  tatement..** Aut
35510 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
35520 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20  re-enabled by a 
35530 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c  [COMMIT] or [ROL
35540 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  LBACK]..**.** If
35550 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f   certain kinds o
35560 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f  f errors occur o
35570 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69  n a statement wi
35580 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61  thin a multi-sta
35590 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61  tement.** transa
355a0 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e  ction (errors in
355b0 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f  cluding [SQLITE_
355c0 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  FULL], [SQLITE_I
355d0 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  OERR],.** [SQLIT
355e0 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54  E_NOMEM], [SQLIT
355f0 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51  E_BUSY], and [SQ
35600 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29  LITE_INTERRUPT])
35610 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61   then the.** tra
35620 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62  nsaction might b
35630 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
35640 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
35650 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a  e only way to.**
35660 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65   find out whethe
35670 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  r SQLite automat
35680 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
35690 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
356a0 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65  on after.** an e
356b0 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74  rror is to use t
356c0 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
356d0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
356e0 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 31 7d 20 54  **.** {H12931} T
356f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  he [sqlite3_get_
35700 61 75 74 6f 63 6f 6d 6d 69 74 28 44 29 5d 20 69  autocommit(D)] i
35710 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
35720 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20   non-zero or.** 
35730 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 69 66           zero if
35740 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
35750 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69 73 20  onnection] D is 
35760 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
35770 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20 20 20 20 20  ocommit.**      
35780 20 20 20 20 6d 6f 64 65 2c 20 72 65 73 70 65 63      mode, respec
35790 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tively..**.** {H
357a0 31 32 39 33 32 7d 20 41 75 74 6f 63 6f 6d 6d 69  12932} Autocommi
357b0 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20  t mode is on by 
357c0 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b  default..**.** {
357d0 48 31 32 39 33 33 7d 20 41 75 74 6f 63 6f 6d 6d  H12933} Autocomm
357e0 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62  it mode is disab
357f0 6c 65 64 20 62 79 20 61 20 73 75 63 63 65 73 73  led by a success
35800 66 75 6c 20 5b 42 45 47 49 4e 5d 20 73 74 61 74  ful [BEGIN] stat
35810 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ement..**.** {H1
35820 32 39 33 34 7d 20 41 75 74 6f 63 6f 6d 6d 69 74  2934} Autocommit
35830 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
35840 20 62 79 20 61 20 73 75 63 63 65 73 73 66 75 6c   by a successful
35850 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
35860 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20 20 20 20 20  LLBACK].**      
35870 20 20 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a      statement..*
35880 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
35890 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 39 33 36 7d  :.**.** {A12936}
358a0 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
358b0 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61  ad changes the a
358c0 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73  utocommit status
358d0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
358e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
358f0 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
35900 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75  is routine is ru
35910 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nning, then the 
35920 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
35930 20 20 20 20 20 20 20 20 20 69 73 20 75 6e 64 65           is unde
35940 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
35950 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
35960 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  mmit(sqlite3*);.
35970 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35980 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61   Find The Databa
35990 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50  se Handle Of A P
359a0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
359b0 74 20 7b 48 31 33 31 32 30 7d 20 3c 53 36 30 36  t {H13120} <S606
359c0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
359d0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
359e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
359f0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
35a00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
35a10 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61  le.** to which a
35a20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
35a30 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20  ment] belongs.  
35a40 54 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  The database han
35a50 64 6c 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a  dle returned by.
35a60 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  ** sqlite3_db_ha
35a70 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65  ndle is the same
35a80 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
35a90 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69   that was the fi
35aa0 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
35ab0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
35ac0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61  prepare_v2()] ca
35ad0 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61  ll (or its varia
35ae0 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73  nts) that was us
35af0 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20  ed to.** create 
35b00 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  the statement in
35b10 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65   the first place
35b20 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
35b30 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 32  TS:.**.** {H1312
35b40 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
35b50 64 62 5f 68 61 6e 64 6c 65 28 53 29 5d 20 69 6e  db_handle(S)] in
35b60 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
35b70 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20  a pointer.**    
35b80 20 20 20 20 20 20 74 6f 20 74 68 65 20 5b 64 61        to the [da
35b90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35ba0 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  n] associated wi
35bb0 74 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  th the.**       
35bc0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
35bd0 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71  tement] S..*/.sq
35be0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
35bf0 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
35c00 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
35c10 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74  CAPI3REF: Find t
35c20 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64  he next prepared
35c30 20 73 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31   statement {H131
35c40 34 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a  40} <S60600>.**.
35c50 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
35c60 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
35c70 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ter to the next 
35c80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
35c90 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53  ent] after.** pS
35ca0 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  tmt associated w
35cb0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
35cc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44  e connection] pD
35cd0 62 2e 20 20 49 66 20 70 53 74 6d 74 20 69 73 20  b.  If pStmt is 
35ce0 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69  NULL.** then thi
35cf0 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
35d00 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
35d10 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61   the first prepa
35d20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
35d30 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
35d40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
35d50 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 49  nnection pDb.  I
35d60 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74  f no prepared st
35d70 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73  atement.** satis
35d80 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69  fies the conditi
35d90 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ons of this rout
35da0 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ine, it returns 
35db0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  NULL..**.** INVA
35dc0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
35dd0 31 33 31 34 33 7d 20 49 66 20 44 20 69 73 20 61  13143} If D is a
35de0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35df0 63 74 69 6f 6e 5d 20 74 68 61 74 20 68 6f 6c 64  ction] that hold
35e00 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
35e10 20 20 20 20 20 20 20 20 20 20 75 6e 66 69 6e 61            unfina
35e20 6c 69 7a 65 64 20 5b 70 72 65 70 61 72 65 64 20  lized [prepared 
35e30 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20  statements] and 
35e40 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  S is a NULL poin
35e50 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ter,.**         
35e60 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6e   then [sqlite3_n
35e70 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20  ext_stmt(D, S)] 
35e80 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65  routine shall re
35e90 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  turn a pointer.*
35ea0 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 6f 6e  *          to on
35eb0 65 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65  e of the prepare
35ec0 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73  d statements ass
35ed0 6f 63 69 61 74 65 64 20 77 69 74 68 20 44 2e 0a  ociated with D..
35ee0 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 36 7d 20 49  **.** {H13146} I
35ef0 66 20 44 20 69 73 20 61 20 5b 64 61 74 61 62 61  f D is a [databa
35f00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
35f10 68 61 74 20 68 6f 6c 64 73 20 6e 6f 20 75 6e 66  hat holds no unf
35f20 69 6e 61 6c 69 7a 65 64 0a 2a 2a 20 20 20 20 20  inalized.**     
35f30 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
35f40 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53  tatements] and S
35f50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
35f60 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  er, then.**     
35f70 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65       [sqlite3_ne
35f80 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72  xt_stmt(D, S)] r
35f90 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74  outine shall ret
35fa0 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  urn a NULL point
35fb0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34  er..**.** {H1314
35fc0 39 7d 20 49 66 20 53 20 69 73 20 61 20 5b 70 72  9} If S is a [pr
35fd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
35fe0 5d 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61  ] in the [databa
35ff0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
36000 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
36010 20 53 20 69 73 20 6e 6f 74 20 74 68 65 20 6c 61   S is not the la
36020 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
36030 65 6d 65 6e 74 20 69 6e 20 44 2c 20 74 68 65 6e  ement in D, then
36040 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
36050 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
36060 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73  D, S)] routine s
36070 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 70 6f  hall return a po
36080 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  inter.**        
36090 20 20 74 6f 20 74 68 65 20 6e 65 78 74 20 70 72    to the next pr
360a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
360b0 20 69 6e 20 44 20 61 66 74 65 72 20 53 2e 0a 2a   in D after S..*
360c0 2a 0a 2a 2a 20 7b 48 31 33 31 35 32 7d 20 49 66  *.** {H13152} If
360d0 20 53 20 69 73 20 74 68 65 20 6c 61 73 74 20 5b   S is the last [
360e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
360f0 6e 74 5d 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  nt] in the.**   
36100 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
36110 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74   connection] D t
36120 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
36130 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29  _next_stmt(D, S)
36140 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f  ].**          ro
36150 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75  utine shall retu
36160 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  rn a NULL pointe
36170 72 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54  r..**.** ASSUMPT
36180 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 33  IONS:.**.** {A13
36190 31 35 34 7d 20 54 68 65 20 5b 64 61 74 61 62 61  154} The [databa
361a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
361b0 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61  ointer D in a ca
361c0 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ll to.**        
361d0 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f    [sqlite3_next_
361e0 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20  stmt(D,S)] must 
361f0 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e  refer to an open
36200 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20   database.**    
36210 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e        connection
36220 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c   and in particul
36230 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61  ar must not be a
36240 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
36250 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  /.sqlite3_stmt *
36260 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
36270 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20  t(sqlite3 *pDb, 
36280 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
36290 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
362a0 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e  I3REF: Commit An
362b0 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66  d Rollback Notif
362c0 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
362d0 73 20 7b 48 31 32 39 35 30 7d 20 3c 53 36 30 34  s {H12950} <S604
362e0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
362f0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
36300 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
36310 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
36320 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
36330 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
36340 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
36350 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64  ion is committed
36360 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63  ..** Any callbac
36370 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
36380 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ous call to sqli
36390 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
363a0 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
363b0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
363c0 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
363d0 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  den..** The sqli
363e0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
363f0 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
36400 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
36410 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
36420 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
36430 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
36440 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64  ion is committed
36450 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63  ..** Any callbac
36460 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
36470 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ous call to sqli
36480 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
36490 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
364a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
364b0 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
364c0 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67  den..** The pArg
364d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73   argument is pas
364e0 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74  sed through to t
364f0 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  he callback..** 
36500 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
36510 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b  on a commit hook
36520 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
36530 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74  s non-zero,.** t
36540 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69  hen the commit i
36550 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
36560 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a   a rollback..**.
36570 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75  ** If another fu
36580 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69  nction was previ
36590 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64  ously registered
365a0 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67 20 76 61  , its.** pArg va
365b0 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
365c0 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c    Otherwise NULL
365d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
365e0 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 6e 67 20  .** Registering 
365f0 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20  a NULL function 
36600 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c  disables the cal
36610 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  lback..**.** For
36620 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
36630 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61   this API, a tra
36640 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64  nsaction is said
36650 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a   to have been.**
36660 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20   rolled back if 
36670 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c  an explicit "ROL
36680 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74  LBACK" statement
36690 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72   is executed, or
366a0 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  .** an error or 
366b0 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65  constraint cause
366c0 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f  s an implicit ro
366d0 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e  llback to occur.
366e0 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b  .** The rollback
366f0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74   callback is not
36700 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72   invoked if a tr
36710 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20  ansaction is.** 
36720 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
36730 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73  lled back becaus
36740 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
36750 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
36760 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c  sed..** The roll
36770 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  back callback is
36780 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20   not invoked if 
36790 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
367a0 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
367b0 62 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74  because a commit
367c0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
367d0 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20  ed non-zero..** 
367e0 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20  <todo> Check on 
367f0 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  this </todo>.**.
36800 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
36810 2a 0a 2a 2a 20 7b 48 31 32 39 35 31 7d 20 54 68  *.** {H12951} Th
36820 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  e [sqlite3_commi
36830 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  t_hook(D,F,P)] i
36840 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
36850 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  rs the.**       
36860 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63     callback func
36870 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76  tion F to be inv
36880 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65  oked with argume
36890 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a  nt P whenever.**
368a0 20 20 20 20 20 20 20 20 20 20 61 20 74 72 61 6e            a tran
368b0 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 20  saction commits 
368c0 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
368d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
368e0 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 32 7d 20 54  **.** {H12952} T
368f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  he [sqlite3_comm
36900 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  it_hook(D,F,P)] 
36910 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
36920 73 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74  s the P argument
36930 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f  .**          fro
36940 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  m the previous c
36950 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61 6d  all with the sam
36960 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
36970 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20  ection] D,.**   
36980 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 6f         or NULL o
36990 6e 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  n the first call
369a0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
369b0 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
369c0 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  ction D..**.** {
369d0 48 31 32 39 35 33 7d 20 45 61 63 68 20 63 61 6c  H12953} Each cal
369e0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
369f0 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65  mmit_hook()] ove
36a00 72 77 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c  rwrites the call
36a10 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
36a20 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 70   registered by p
36a30 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a  rior calls..**.*
36a40 2a 20 7b 48 31 32 39 35 34 7d 20 49 66 20 74 68  * {H12954} If th
36a50 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  e F argument to 
36a60 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
36a70 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20  hook(D,F,P)] is 
36a80 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  NULL.**         
36a90 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
36aa0 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69   hook callback i
36ab0 73 20 63 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e  s canceled and n
36ac0 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  o callback.**   
36ad0 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65         is invoke
36ae0 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63  d when a transac
36af0 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a 2a 2a  tion commits..**
36b00 0a 2a 2a 20 7b 48 31 32 39 35 35 7d 20 49 66 20  .** {H12955} If 
36b10 74 68 65 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62  the commit callb
36b20 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
36b30 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20 63 6f  zero then the co
36b40 6d 6d 69 74 20 69 73 0a 2a 2a 20 20 20 20 20 20  mmit is.**      
36b50 20 20 20 20 63 6f 6e 76 65 72 74 65 64 20 69 6e      converted in
36b60 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  to a rollback..*
36b70 2a 0a 2a 2a 20 7b 48 31 32 39 36 31 7d 20 54 68  *.** {H12961} Th
36b80 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  e [sqlite3_rollb
36b90 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  ack_hook(D,F,P)]
36ba0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
36bb0 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ters the.**     
36bc0 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75       callback fu
36bd0 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69  nction F to be i
36be0 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75  nvoked with argu
36bf0 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a  ment P whenever.
36c00 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 72  **          a tr
36c10 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20  ansaction rolls 
36c20 62 61 63 6b 20 6f 6e 20 74 68 65 20 5b 64 61 74  back on the [dat
36c30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36c40 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ] D..**.** {H129
36c50 36 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  62} The [sqlite3
36c60 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
36c70 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
36c80 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 0a 2a   returns the P.*
36c90 2a 20 20 20 20 20 20 20 20 20 20 61 72 67 75 6d  *          argum
36ca0 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
36cb0 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20  vious call with 
36cc0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20  the same.**     
36cd0 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
36ce0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72  onnection] D, or
36cf0 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72   NULL on the fir
36d00 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  st call.**      
36d10 20 20 20 20 66 6f 72 20 61 20 70 61 72 74 69 63      for a partic
36d20 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 63 6f  ular database co
36d30 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a  nnection D..**.*
36d40 2a 20 7b 48 31 32 39 36 33 7d 20 45 61 63 68 20  * {H12963} Each 
36d50 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
36d60 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
36d70 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65  ] overwrites the
36d80 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
36d90 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64        registered
36da0 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e   by prior calls.
36db0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 34 7d 20  .**.** {H12964} 
36dc0 49 66 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e  If the F argumen
36dd0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f  t to [sqlite3_ro
36de0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c  llback_hook(D,F,
36df0 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20  P)] is NULL.**  
36e00 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65          then the
36e10 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63   rollback hook c
36e20 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65  allback is cance
36e30 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62  led and no callb
36e40 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
36e50 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
36e60 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f  a transaction ro
36e70 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76 6f 69  lls back..*/.voi
36e80 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  d *sqlite3_commi
36e90 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  t_hook(sqlite3*,
36ea0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
36eb0 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71  void*);.void *sq
36ec0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
36ed0 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ook(sqlite3*, vo
36ee0 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76  id(*)(void *), v
36ef0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
36f00 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61  PI3REF: Data Cha
36f10 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  nge Notification
36f20 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39   Callbacks {H129
36f30 37 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a  70} <S60400>.**.
36f40 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
36f50 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74  pdate_hook() int
36f60 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
36f70 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
36f80 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
36f90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36fa0 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65  ction] identifie
36fb0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
36fc0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65  rgument.** to be
36fd0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
36fe0 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74  r a row is updat
36ff0 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20  ed, inserted or 
37000 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  deleted..** Any 
37010 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
37020 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
37030 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
37040 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
37050 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
37060 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
37070 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  en..**.** The se
37080 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
37090 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
370a0 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e  e function to in
370b0 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72  voke when a.** r
370c0 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
370d0 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
370e0 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ed..** The first
370f0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
37100 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
37110 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
37120 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
37130 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
37140 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65  ook()..** The se
37150 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72  cond callback ar
37160 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
37170 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d   [SQLITE_INSERT]
37180 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  , [SQLITE_DELETE
37190 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
371a0 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64  _UPDATE], depend
371b0 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61  ing on the opera
371c0 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64  tion that caused
371d0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
371e0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a   to be invoked..
371f0 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64  ** The third and
37200 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
37210 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
37220 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65  k contain pointe
37230 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  rs to the.** dat
37240 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20  abase and table 
37250 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  name containing 
37260 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77  the affected row
37270 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63  ..** The final c
37280 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
37290 72 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 6f  r is the rowid o
372a0 66 20 74 68 65 20 72 6f 77 2e 20 49 6e 20 74 68  f the row. In th
372b0 65 20 63 61 73 65 20 6f 66 0a 2a 2a 20 61 6e 20  e case of.** an 
372c0 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20  update, this is 
372d0 74 68 65 20 72 6f 77 69 64 20 61 66 74 65 72 20  the rowid after 
372e0 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73  the update takes
372f0 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   place..**.** Th
37300 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73  e update hook is
37310 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65   not invoked whe
37320 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65  n internal syste
37330 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20  m tables are.** 
37340 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73  modified (i.e. s
37350 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64  qlite_master and
37360 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65   sqlite_sequence
37370 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  )..**.** If anot
37380 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73  her function was
37390 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69   previously regi
373a0 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 72 67  stered, its pArg
373b0 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74   value.** is ret
373c0 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
373d0 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  e NULL is return
373e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
373f0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
37400 39 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  971} The [sqlite
37410 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
37420 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,P)] interface 
37430 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
37440 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
37450 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65  function F to be
37460 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 69   invoked with fi
37470 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 50 20  rst parameter P 
37480 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20  whenever.**     
37490 20 20 20 20 20 61 20 74 61 62 6c 65 20 72 6f 77       a table row
374a0 20 69 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e   is modified, in
374b0 73 65 72 74 65 64 2c 20 6f 72 20 64 65 6c 65 74  serted, or delet
374c0 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ed on.**        
374d0 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20    the [database 
374e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
374f0 2a 0a 2a 2a 20 7b 48 31 32 39 37 33 7d 20 54 68  *.** {H12973} Th
37500 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
37510 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  e_hook(D,F,P)] i
37520 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
37530 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20   the value.**   
37540 20 20 20 20 20 20 20 6f 66 20 50 20 66 6f 72 20         of P for 
37550 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
37560 6c 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  l on the same [d
37570 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37580 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20  on] D,.**       
37590 20 20 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 20 74     or NULL for t
375a0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 2e 0a 2a  he first call..*
375b0 2a 0a 2a 2a 20 7b 48 31 32 39 37 35 7d 20 49 66  *.** {H12975} If
375c0 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
375d0 20 63 61 6c 6c 62 61 63 6b 20 46 20 69 6e 20 5b   callback F in [
375e0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
375f0 6f 6f 6b 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20  ook(D,F,P)].**  
37600 20 20 20 20 20 20 20 20 69 73 20 4e 55 4c 4c 20          is NULL 
37610 74 68 65 6e 20 74 68 65 20 6e 6f 20 75 70 64 61  then the no upda
37620 74 65 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65  te callbacks are
37630 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   made..**.** {H1
37640 32 39 37 37 7d 20 45 61 63 68 20 63 61 6c 6c 20  2977} Each call 
37650 74 6f 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  to [sqlite3_upda
37660 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  te_hook(D,F,P)] 
37670 6f 76 65 72 72 69 64 65 73 20 70 72 69 6f 72 20  overrides prior 
37680 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20  calls.**        
37690 20 20 74 6f 20 74 68 65 20 73 61 6d 65 20 69 6e    to the same in
376a0 74 65 72 66 61 63 65 20 6f 6e 20 74 68 65 20 73  terface on the s
376b0 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
376c0 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
376d0 2a 2a 20 7b 48 31 32 39 37 39 7d 20 54 68 65 20  ** {H12979} The 
376e0 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c  update hook call
376f0 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
37700 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
37710 6c 20 73 79 73 74 65 6d 0a 2a 2a 20 20 20 20 20  l system.**     
37720 20 20 20 20 20 74 61 62 6c 65 73 20 73 75 63 68       tables such
37730 20 61 73 20 73 71 6c 69 74 65 5f 6d 61 73 74 65   as sqlite_maste
37740 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
37750 75 65 6e 63 65 20 61 72 65 20 6d 6f 64 69 66 69  uence are modifi
37760 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 38  ed..**.** {H1298
37770 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  1} The second pa
37780 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 75  rameter to the u
37790 70 64 61 74 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  pdate callback.*
377a0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6f 6e  *          is on
377b0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53  e of [SQLITE_INS
377c0 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45  ERT], [SQLITE_DE
377d0 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LETE] or [SQLITE
377e0 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 20 20 20  _UPDATE],.**    
377f0 20 20 20 20 20 20 64 65 70 65 6e 64 69 6e 67 20        depending 
37800 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
37810 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
37820 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20   callback to be 
37830 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  invoked..**.** {
37840 48 31 32 39 38 33 7d 20 54 68 65 20 74 68 69 72  H12983} The thir
37850 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67  d and fourth arg
37860 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61  uments to the ca
37870 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70  llback contain p
37880 6f 69 6e 74 65 72 73 0a 2a 2a 20 20 20 20 20 20  ointers.**      
37890 20 20 20 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d      to zero-term
378a0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
378b0 69 6e 67 73 20 77 68 69 63 68 20 61 72 65 20 74  ings which are t
378c0 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  he names of the.
378d0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61  **          data
378e0 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 74  base and table t
378f0 68 61 74 20 69 73 20 62 65 69 6e 67 20 75 70 64  hat is being upd
37900 61 74 65 64 2e 0a 0a 2a 2a 20 7b 48 31 32 39 38  ated...** {H1298
37910 35 7d 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  5} The final cal
37920 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
37930 69 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  is the rowid of 
37940 74 68 65 20 72 6f 77 20 61 66 74 65 72 0a 2a 2a  the row after.**
37950 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 68            the ch
37960 61 6e 67 65 20 6f 63 63 75 72 73 2e 0a 2a 2f 0a  ange occurs..*/.
37970 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70  void *sqlite3_up
37980 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c  date_hook(.  sql
37990 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  ite3*, .  void(*
379a0 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68  )(void *,int ,ch
379b0 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20  ar const *,char 
379c0 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f  const *,sqlite3_
379d0 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a  int64),.  void*.
379e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
379f0 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
37a00 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67  sable Shared Pag
37a10 65 72 20 43 61 63 68 65 20 7b 48 31 30 33 33 30  er Cache {H10330
37a20 7d 20 3c 53 33 30 39 30 30 3e 0a 2a 2a 20 4b 45  } <S30900>.** KE
37a30 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20  YWORDS: {shared 
37a40 63 61 63 68 65 7d 20 7b 73 68 61 72 65 64 20 63  cache} {shared c
37a50 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a  ache mode}.**.**
37a60 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e   This routine en
37a70 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
37a80 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
37a90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
37aa0 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
37ab0 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  a data structure
37ac0 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62  s between [datab
37ad0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c  ase connection |
37ae0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a   connections].**
37af0 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
37b00 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69  abase. Sharing i
37b10 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
37b20 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
37b30 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65  e.** and disable
37b40 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
37b50 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a  t is false..**.*
37b60 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e 67 20  * Cache sharing 
37b70 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64  is enabled and d
37b80 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65  isabled for an e
37b90 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 20 7b  ntire process. {
37ba0 45 4e 44 7d 0a 2a 2a 20 54 68 69 73 20 69 73 20  END}.** This is 
37bb0 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53  a change as of S
37bc0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
37bd0 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65  5.0. In prior ve
37be0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
37bf0 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73  ,.** sharing was
37c00 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
37c10 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68  bled for each th
37c20 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e  read separately.
37c30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65  .**.** The cache
37c40 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65   sharing mode se
37c50 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66  t by this interf
37c60 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20  ace effects all 
37c70 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  subsequent.** ca
37c80 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
37c90 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
37ca0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e  3_open_v2()], an
37cb0 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  d [sqlite3_open1
37cc0 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  6()]..** Existin
37cd0 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  g database conne
37ce0 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
37cf0 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20  use the sharing 
37d00 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73  mode.** that was
37d10 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68   in effect at th
37d20 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65  e time they were
37d30 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56   opened..**.** V
37d40 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61  irtual tables ca
37d50 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69 74  nnot be used wit
37d60 68 20 61 20 73 68 61 72 65 64 20 63 61 63 68 65  h a shared cache
37d70 2e 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a  .  When shared.*
37d80 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
37d90 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ed, the [sqlite3
37da0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29  _create_module()
37db0 5d 20 41 50 49 20 75 73 65 64 20 74 6f 20 72 65  ] API used to re
37dc0 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61  gister.** virtua
37dd0 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c  l tables will al
37de0 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65  ways return an e
37df0 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  rror..**.** This
37e00 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
37e10 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20   [SQLITE_OK] if 
37e20 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73  shared cache was
37e30 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
37e40 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66  bled.** successf
37e50 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72  ully.  An [error
37e60 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
37e70 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
37e80 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 65  .** Shared cache
37e90 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
37ea0 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69  default. But thi
37eb0 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  s might change i
37ec0 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65  n.** future rele
37ed0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ases of SQLite. 
37ee0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
37ef0 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73 68  at care about sh
37f00 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65  ared.** cache se
37f10 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74  tting should set
37f20 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a   it explicitly..
37f30 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
37f40 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 33 33 31 7d  :.**.** {H10331}
37f50 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
37f60 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
37f70 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
37f80 65 64 5f 63 61 63 68 65 28 42 29 5d 0a 2a 2a 20  ed_cache(B)].** 
37f90 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 65 6e           will en
37fa0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
37fb0 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
37fc0 65 20 66 6f 72 20 61 6e 79 20 73 75 62 73 65 71  e for any subseq
37fd0 75 65 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20  uently.**       
37fe0 20 20 20 63 72 65 61 74 65 64 20 5b 64 61 74 61     created [data
37ff0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
38000 20 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f   in the same pro
38010 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  cess..**.** {H10
38020 33 33 36 7d 20 57 68 65 6e 20 73 68 61 72 65 64  336} When shared
38030 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
38040 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d, the [sqlite3_
38050 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d  create_module()]
38060 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
38070 65 72 66 61 63 65 20 77 69 6c 6c 20 61 6c 77 61  erface will alwa
38080 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  ys return an err
38090 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 33 33  or..**.** {H1033
380a0 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
380b0 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
380c0 63 68 65 28 42 29 5d 20 69 6e 74 65 72 66 61 63  che(B)] interfac
380d0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
380e0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b        [SQLITE_OK
380f0 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68  ] if shared cach
38100 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72  e was enabled or
38110 20 64 69 73 61 62 6c 65 64 20 73 75 63 63 65 73   disabled succes
38120 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  sfully..**.** {H
38130 31 30 33 33 39 7d 20 53 68 61 72 65 64 20 63 61  10339} Shared ca
38140 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  che is disabled 
38150 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69  by default..*/.i
38160 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  nt sqlite3_enabl
38170 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69  e_shared_cache(i
38180 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
38190 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f  3REF: Attempt To
381a0 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72   Free Heap Memor
381b0 79 20 7b 48 31 37 33 34 30 7d 20 3c 53 33 30 32  y {H17340} <S302
381c0 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  20>.**.** The sq
381d0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
381e0 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 65  mory() interface
381f0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65   attempts to fre
38200 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  e N bytes.** of 
38210 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64  heap memory by d
38220 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d  eallocating non-
38230 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79  essential memory
38240 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20   allocations.** 
38250 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61  held by the data
38260 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20 7b 45  base library. {E
38270 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65 64  ND}  Memory used
38280 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61   to cache databa
38290 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69  se.** pages to i
382a0 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
382b0 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  ce is an example
382c0 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61   of non-essentia
382d0 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 73 71 6c  l memory..** sql
382e0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
382f0 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 68  ory() returns th
38300 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
38310 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64  s actually freed
38320 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74  ,.** which might
38330 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73   be more or less
38340 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74   than the amount
38350 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a   requested..**.*
38360 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
38370 0a 2a 2a 20 7b 48 31 37 33 34 31 7d 20 54 68 65  .** {H17341} The
38380 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
38390 65 5f 6d 65 6d 6f 72 79 28 4e 29 5d 20 69 6e 74  e_memory(N)] int
383a0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
383b0 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  to.**          f
383c0 72 65 65 20 4e 20 62 79 74 65 73 20 6f 66 20 68  ree N bytes of h
383d0 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65  eap memory by de
383e0 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65  allocating non-e
383f0 73 73 65 6e 74 69 61 6c 0a 2a 2a 20 20 20 20 20  ssential.**     
38400 20 20 20 20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f       memory allo
38410 63 61 74 69 6f 6e 73 20 68 65 6c 64 20 62 79 20  cations held by 
38420 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62  the database lib
38430 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  rary..**.** {H16
38440 33 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  342} The [sqlite
38450 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
38460 28 4e 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65  (N)] returns the
38470 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20   number.**      
38480 20 20 20 20 6f 66 20 62 79 74 65 73 20 61 63 74      of bytes act
38490 75 61 6c 6c 79 20 66 72 65 65 64 2c 20 77 68 69  ually freed, whi
384a0 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72 65  ch might be more
384b0 20 6f 72 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20   or less.**     
384c0 20 20 20 20 20 74 68 61 6e 20 74 68 65 20 61 6d       than the am
384d0 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a  ount requested..
384e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
384f0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e  elease_memory(in
38500 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
38510 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69  REF: Impose A Li
38520 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65  mit On Heap Size
38530 20 7b 48 31 37 33 35 30 7d 20 3c 53 33 30 32 32   {H17350} <S3022
38540 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
38550 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
38560 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  imit() interface
38570 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22   places a "soft"
38580 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65   limit.** on the
38590 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20   amount of heap 
385a0 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20  memory that may 
385b0 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  be allocated by 
385c0 53 51 4c 69 74 65 2e 0a 2a 2a 20 49 66 20 61 6e  SQLite..** If an
385d0 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61   internal alloca
385e0 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
385f0 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63  d that would exc
38600 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20  eed the.** soft 
38610 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c  heap limit, [sql
38620 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
38630 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ory()] is invoke
38640 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65  d one or.** more
38650 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75   times to free u
38660 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66  p some space bef
38670 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69  ore the allocati
38680 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
38690 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d 69 74  .**.** The limit
386a0 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74   is called "soft
386b0 22 2c 20 62 65 63 61 75 73 65 20 69 66 20 5b 73  ", because if [s
386c0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
386d0 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e  emory()].** cann
386e0 6f 74 20 66 72 65 65 20 73 75 66 66 69 63 69 65  ot free sufficie
386f0 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65  nt memory to pre
38700 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66  vent the limit f
38710 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64  rom being exceed
38720 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72  ed,.** the memor
38730 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61  y is allocated a
38740 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 75  nyway and the cu
38750 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20  rrent operation 
38760 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  proceeds..**.** 
38770 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a 65  A negative or ze
38780 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20 6d  ro value for N m
38790 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65 20  eans that there 
387a0 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70 20  is no soft heap 
387b0 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73 71  limit and.** [sq
387c0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
387d0 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c  mory()] will onl
387e0 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
387f0 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61 75   memory is exhau
38800 73 74 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65 66  sted..** The def
38810 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74  ault value for t
38820 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
38830 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  it is zero..**.*
38840 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  * SQLite makes a
38850 20 62 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20   best effort to 
38860 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68  honor the soft h
38870 65 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 42 75  eap limit..** Bu
38880 74 20 69 66 20 74 68 65 20 73 6f 66 74 20 68 65  t if the soft he
38890 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20  ap limit cannot 
388a0 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63  be honored, exec
388b0 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f  ution will.** co
388c0 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65  ntinue without e
388d0 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61  rror or notifica
388