/ Hex Artifact Content
Login

Artifact 1980ef5f4f36ae986f3bf1d54ee322c967b69923:


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 33 20 32 30 30 38 2f 30  n,v 1.383 2008/0
05f0: 37 2f 33 31 20 31 34 3a 34 37 3a 35 35 20 64 72  7/31 14:47:55 dr
0600: 68 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66 6e 64  h Exp $.*/.#ifnd
0610: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ef _SQLITE3_H_.#
0620: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f  define _SQLITE3_
0630: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64  H_.#include <std
0640: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65  arg.h>     /* Ne
0650: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66  eded for the def
0660: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69  inition of va_li
0670: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  st */../*.** Mak
0680: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61  e sure we can ca
0690: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72  ll this stuff fr
06a0: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65  om C++..*/.#ifde
06b0: 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78  f __cplusplus.ex
06c0: 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69  tern "C" {.#endi
06d0: 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74 68  f.../*.** Add th
06e0: 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65  e ability to ove
06f0: 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a 2a  rride 'extern'.*
0700: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
0710: 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65  _EXTERN.# define
0720: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65   SQLITE_EXTERN e
0730: 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  xtern.#endif../*
0740: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0750: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0760: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0770: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0780: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0790: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
07a0: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
07b0: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
07c0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
07d0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
07e0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
07f0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0800: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0810: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0820: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0830: 75 6d 62 65 72 73 20 7b 48 31 30 30 31 30 7d 20  umbers {H10010} 
0840: 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60100>.**.** T
0850: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0860: 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f 56 45 52  N and SQLITE_VER
0870: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 64 65 66  SION_NUMBER #def
0880: 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68 65 20 73  ines in.** the s
0890: 71 6c 69 74 65 33 2e 68 20 66 69 6c 65 20 73 70  qlite3.h file sp
08a0: 65 63 69 66 79 20 74 68 65 20 76 65 72 73 69 6f  ecify the versio
08b0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 77 69 74 68  n of SQLite with
08c0: 20 77 68 69 63 68 0a 2a 2a 20 74 68 61 74 20 68   which.** that h
08d0: 65 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73  eader file is as
08e0: 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  sociated..**.** 
08f0: 54 68 65 20 22 76 65 72 73 69 6f 6e 22 20 6f 66  The "version" of
0900: 20 53 51 4c 69 74 65 20 69 73 20 61 20 73 74 72   SQLite is a str
0910: 69 6e 67 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ing of the form 
0920: 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54 68 65 20  "X.Y.Z"..** The 
0930: 70 68 72 61 73 65 20 22 61 6c 70 68 61 22 20 6f  phrase "alpha" o
0940: 72 20 22 62 65 74 61 22 20 6d 69 67 68 74 20 62  r "beta" might b
0950: 65 20 61 70 70 65 6e 64 65 64 20 61 66 74 65 72  e appended after
0960: 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68 65 20 58   the Z..** The X
0970: 20 76 61 6c 75 65 20 69 73 20 6d 61 6a 6f 72 20   value is major 
0980: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0990: 6c 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69 74  lways 3 in SQLit
09a0: 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c  e3..** The X val
09b0: 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20  ue only changes 
09c0: 77 68 65 6e 20 62 61 63 6b 77 61 72 64 73 20 63  when backwards c
09d0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73 0a  ompatibility is.
09e0: 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77 65  ** broken and we
09f0: 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65 72   intend to never
0a00: 20 62 72 65 61 6b 20 62 61 63 6b 77 61 72 64 73   break backwards
0a10: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
0a20: 2a 2a 20 54 68 65 20 59 20 76 61 6c 75 65 20 69  ** The Y value i
0a30: 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73  s the minor vers
0a40: 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 6f  ion number and o
0a50: 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 6e  nly changes when
0a60: 0a 2a 2a 20 74 68 65 72 65 20 61 72 65 20 6d 61  .** there are ma
0a70: 6a 6f 72 20 66 65 61 74 75 72 65 20 65 6e 68 61  jor feature enha
0a80: 6e 63 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72  ncements that ar
0a90: 65 20 66 6f 72 77 61 72 64 73 20 63 6f 6d 70 61  e forwards compa
0aa0: 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e 6f 74  tible.** but not
0ab0: 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
0ac0: 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 5a 20  tible..** The Z 
0ad0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 72 65 6c  value is the rel
0ae0: 65 61 73 65 20 6e 75 6d 62 65 72 20 61 6e 64 20  ease number and 
0af0: 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 77  is incremented w
0b00: 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 65 6c 65  ith.** each rele
0b10: 61 73 65 20 62 75 74 20 72 65 73 65 74 73 20 62  ase but resets b
0b20: 61 63 6b 20 74 6f 20 30 20 77 68 65 6e 65 76 65  ack to 0 wheneve
0b30: 72 20 59 20 69 73 20 69 6e 63 72 65 6d 65 6e 74  r Y is increment
0b40: 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ed..**.** See al
0b50: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
0b60: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
0b70: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
0b80: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e 0a 2a 2a  on_number()]..**
0b90: 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
0ba0: 2a 2a 0a 2a 2a 20 7b 48 31 30 30 31 31 7d 20 54  **.** {H10011} T
0bb0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0bc0: 4e 20 23 64 65 66 69 6e 65 20 69 6e 20 74 68 65  N #define in the
0bd0: 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65   sqlite3.h heade
0be0: 72 20 66 69 6c 65 20 73 68 61 6c 6c 0a 2a 2a 20  r file shall.** 
0bf0: 20 20 20 20 20 20 20 20 20 65 76 61 6c 75 61 74           evaluat
0c00: 65 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  e to a string li
0c10: 74 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68  teral that is th
0c20: 65 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  e SQLite version
0c30: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74  .**          wit
0c40: 68 20 77 68 69 63 68 20 74 68 65 20 68 65 61 64  h which the head
0c50: 65 72 20 66 69 6c 65 20 69 73 20 61 73 73 6f 63  er file is assoc
0c60: 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  iated..**.** {H1
0c70: 30 30 31 34 7d 20 54 68 65 20 53 51 4c 49 54 45  0014} The SQLITE
0c80: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0c90: 23 64 65 66 69 6e 65 20 73 68 61 6c 6c 20 72 65  #define shall re
0ca0: 73 6f 6c 76 65 20 74 6f 20 61 6e 20 69 6e 74 65  solve to an inte
0cb0: 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ger.**          
0cc0: 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20 28  with the value (
0cd0: 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30  X*1000000 + Y*10
0ce0: 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c  00 + Z) where X,
0cf0: 20 59 2c 20 61 6e 64 20 5a 0a 2a 2a 20 20 20 20   Y, and Z.**    
0d00: 20 20 20 20 20 20 61 72 65 20 74 68 65 20 6d 61        are the ma
0d10: 6a 6f 72 20 76 65 72 73 69 6f 6e 2c 20 6d 69 6e  jor version, min
0d20: 6f 72 20 76 65 72 73 69 6f 6e 2c 20 61 6e 64 20  or version, and 
0d30: 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 0a  release number..
0d40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0d50: 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20  E_VERSION       
0d60: 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65    "--VERS--".#de
0d70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
0d80: 49 4f 4e 5f 4e 55 4d 42 45 52 20 20 2d 2d 56 45  ION_NUMBER  --VE
0d90: 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 0a  RSION-NUMBER--..
0da0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
0db0: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
0dc0: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
0dd0: 20 7b 48 31 30 30 32 30 7d 20 3c 53 36 30 31 30   {H10020} <S6010
0de0: 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
0df0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a  sqlite3_version.
0e00: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 65 61 74  **.** These feat
0e10: 75 72 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  ures provide the
0e20: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
0e30: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
0e40: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 61 6e 64  _VERSION].** and
0e50: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0e60: 5f 4e 55 4d 42 45 52 5d 20 23 64 65 66 69 6e 65  _NUMBER] #define
0e70: 73 20 69 6e 20 74 68 65 20 68 65 61 64 65 72 2c  s in the header,
0e80: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
0e90: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
0ea0: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
0eb0: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
0ec0: 6c 65 2e 20 20 43 61 75 74 69 6f 75 73 20 70 72  le.  Cautious pr
0ed0: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 0a  ogrammers might.
0ee0: 2a 2a 20 69 6e 63 6c 75 64 65 20 61 20 63 68 65  ** include a che
0ef0: 63 6b 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c  ck in their appl
0f00: 69 63 61 74 69 6f 6e 20 74 6f 20 76 65 72 69 66  ication to verif
0f10: 79 20 74 68 61 74 0a 2a 2a 20 73 71 6c 69 74 65  y that.** sqlite
0f20: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
0f30: 62 65 72 28 29 20 61 6c 77 61 79 73 20 72 65 74  ber() always ret
0f40: 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 0a 2a  urns the value.*
0f50: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  * [SQLITE_VERSIO
0f60: 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a  N_NUMBER]..**.**
0f70: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62   The sqlite3_lib
0f80: 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69  version() functi
0f90: 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  on returns the s
0fa0: 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
0fb0: 61 73 20 69 73 0a 2a 2a 20 69 6e 20 74 68 65 20  as is.** in the 
0fc0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
0fd0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
0fe0: 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e  t.  The function
0ff0: 20 69 73 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20   is provided.** 
1000: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
1010: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
1020: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
1030: 61 76 65 20 64 69 72 65 63 74 20 61 63 63 65 73  ave direct acces
1040: 73 20 74 6f 20 73 74 72 69 6e 67 0a 2a 2a 20 63  s to string.** c
1050: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
1060: 74 68 65 20 44 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49  the DLL..**.** I
1070: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1080: 20 7b 48 31 30 30 32 31 7d 20 54 68 65 20 5b 73   {H10021} The [s
1090: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
10a0: 6e 5f 6e 75 6d 62 65 72 28 29 5d 20 69 6e 74 65  n_number()] inte
10b0: 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75  rface shall retu
10c0: 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  rn.**          a
10d0: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
10e0: 74 6f 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  to [SQLITE_VERSI
10f0: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a  ON_NUMBER]..**.*
1100: 2a 20 7b 48 31 30 30 32 32 7d 20 54 68 65 20 5b  * {H10022} The [
1110: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5d  sqlite3_version]
1120: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1130: 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 0a 2a   shall contain.*
1140: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 74  *          the t
1150: 65 78 74 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ext of the [SQLI
1160: 54 45 5f 56 45 52 53 49 4f 4e 5d 20 73 74 72 69  TE_VERSION] stri
1170: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32  ng..**.** {H1002
1180: 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
1190: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 66 75  libversion()] fu
11a0: 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74  nction shall ret
11b0: 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
11c0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
11d0: 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f   [sqlite3_versio
11e0: 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  n] string consta
11f0: 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  nt..*/.SQLITE_EX
1200: 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20  TERN const char 
1210: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
1220: 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  ];.const char *s
1230: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1240: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
1250: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1260: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1280: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1290: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
12a0: 65 61 64 73 61 66 65 20 7b 48 31 30 31 30 30 7d  eadsafe {H10100}
12b0: 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S60100>.**.** 
12c0: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f  SQLite can be co
12d0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77  mpiled with or w
12e0: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20  ithout mutexes. 
12f0: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51   When.** the [SQ
1300: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1310: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1320: 6d 61 63 72 6f 20 69 73 20 74 72 75 65 2c 20 6d  macro is true, m
1330: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
1340: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
1350: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
1360: 20 57 68 65 6e 20 74 68 61 74 20 6d 61 63 72 6f   When that macro
1370: 20 69 73 20 66 61 6c 73 65 2c 0a 2a 2a 20 74 68   is false,.** th
1380: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1390: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
13a0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
13b0: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
13c0: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
13d0: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
13e0: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
13f0: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
1400: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
1410: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
1420: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
1430: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
1440: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
1450: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
1460: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
1470: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
1480: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
1490: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
14a0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
14b0: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68  e enabled..** Th
14c0: 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  e default behavi
14d0: 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65  or is for mutexe
14e0: 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e  s to be enabled.
14f0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1500: 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
1510: 64 20 62 79 20 61 20 70 72 6f 67 72 61 6d 20 74  d by a program t
1520: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
1530: 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20   the.** version 
1540: 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69  of SQLite that i
1550: 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61  t is linking aga
1560: 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65  inst was compile
1570: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65  d with.** the de
1580: 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66  sired setting of
1590: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
15a0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a  EADSAFE] macro..
15b0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
15c0: 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74  face only report
15d0: 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  s on the compile
15e0: 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74  -time mutex sett
15f0: 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53  ing.** of the [S
1600: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1610: 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69  ] flag.  If SQLi
1620: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
1630: 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48  ith.** SQLITE_TH
1640: 52 45 41 44 53 41 46 45 3d 31 20 74 68 65 6e 20  READSAFE=1 then 
1650: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62  mutexes are enab
1660: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62  led by default b
1670: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c  ut.** can be ful
1680: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20  ly or partially 
1690: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61  disabled using a
16a0: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
16b0: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77  3_config()].** w
16c0: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53  ith the verbs [S
16d0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
16e0: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c  GLETHREAD], [SQL
16f0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
1700: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b  THREAD],.** or [
1710: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
1720: 54 45 58 5d 2e 20 20 54 68 65 20 72 65 74 75 72  TEX].  The retur
1730: 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
1740: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 0a 2a  function shows.*
1750: 2a 20 6f 6e 6c 79 20 74 68 65 20 64 65 66 61 75  * only the defau
1760: 6c 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  lt compile-time 
1770: 73 65 74 74 69 6e 67 2c 20 6e 6f 74 20 61 6e 79  setting, not any
1780: 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65   run-time change
1790: 73 0a 2a 2a 20 74 6f 20 74 68 61 74 20 73 65 74  s.** to that set
17a0: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ting..**.** INVA
17b0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
17c0: 31 30 31 30 31 7d 20 54 68 65 20 5b 73 71 6c 69  10101} The [sqli
17d0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
17e0: 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c  ] function shall
17f0: 20 72 65 74 75 72 6e 20 6e 6f 6e 7a 65 72 6f 20   return nonzero 
1800: 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  if.**          S
1810: 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c  QLite was compil
1820: 65 64 20 77 69 74 68 20 74 68 65 20 69 74 73 20  ed with the its 
1830: 6d 75 74 65 78 65 73 20 65 6e 61 62 6c 65 64 20  mutexes enabled 
1840: 62 79 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20  by default.**   
1850: 20 20 20 20 20 20 20 6f 72 20 7a 65 72 6f 20 69         or zero i
1860: 66 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d  f SQLite was com
1870: 70 69 6c 65 64 20 73 75 63 68 20 74 68 61 74 20  piled such that 
1880: 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 20  mutexes are.**  
1890: 20 20 20 20 20 20 20 20 70 65 72 6d 61 6e 65 6e          permanen
18a0: 74 6c 79 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  tly disabled..**
18b0: 0a 2a 2a 20 7b 48 31 30 31 30 32 7d 20 54 68 65  .** {H10102} The
18c0: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
18d0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
18e0: 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 66 75  threadsafe()] fu
18f0: 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  nction.**       
1900: 20 20 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68 61     shall not cha
1910: 6e 67 65 20 77 68 65 6e 20 6d 75 74 65 78 20 73  nge when mutex s
1920: 65 74 74 69 6e 67 20 61 72 65 20 6d 6f 64 69 66  etting are modif
1930: 69 65 64 20 61 74 0a 2a 2a 20 20 20 20 20 20 20  ied at.**       
1940: 20 20 20 72 75 6e 74 69 6d 65 20 75 73 69 6e 67     runtime using
1950: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
1960: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
1970: 65 20 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20  e and .**       
1980: 20 20 20 65 73 70 65 63 69 61 6c 6c 79 20 74 68     especially th
1990: 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
19a0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 0a  _SINGLETHREAD],.
19b0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
19c0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
19d0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
19e0: 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
19f0: 45 44 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ED],.**         
1a00: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
1a10: 46 49 47 5f 4d 55 54 45 58 5d 20 76 65 72 62 73  FIG_MUTEX] verbs
1a20: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1a30: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
1a40: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a50: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
1a60: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 20 7b  nection Handle {
1a70: 48 31 32 30 30 30 7d 20 3c 53 34 30 32 30 30 3e  H12000} <S40200>
1a80: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64  .** KEYWORDS: {d
1a90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1aa0: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f  on} {database co
1ab0: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  nnections}.**.**
1ac0: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74   Each open SQLit
1ad0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65  e database is re
1ae0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70  presented by a p
1af0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
1b00: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  tance of.** the 
1b10: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65  opaque structure
1b20: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22   named "sqlite3"
1b30: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20  .  It is useful 
1b40: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73  to think of an s
1b50: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65  qlite3.** pointe
1b60: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20  r as an object. 
1b70: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   The [sqlite3_op
1b80: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1b90: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a  open16()], and.*
1ba0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
1bb0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
1bc0: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75   are its constru
1bd0: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69  ctors, and [sqli
1be0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20  te3_close()].** 
1bf0: 69 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f  is its destructo
1c00: 72 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  r.  There are ma
1c10: 6e 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61  ny other interfa
1c20: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
1c30: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1c40: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
1c50: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
1c60: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1c70: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1c80: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
1c90: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
1ca0: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
1cb0: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
1cc0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1cd0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
1ce0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
1cf0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
1d00: 65 67 65 72 20 54 79 70 65 73 20 7b 48 31 30 32  eger Types {H102
1d10: 30 30 7d 20 3c 53 31 30 31 31 30 3e 0a 2a 2a 20  00} <S10110>.** 
1d20: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
1d30: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
1d40: 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  nt64.**.** Becau
1d50: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63  se there is no c
1d60: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61  ross-platform wa
1d70: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d  y to specify 64-
1d80: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65  bit integer type
1d90: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c  s.** SQLite incl
1da0: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f  udes typedefs fo
1db0: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  r 64-bit signed 
1dc0: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  and unsigned int
1dd0: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  egers..**.** The
1de0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
1df0: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  nd sqlite3_uint6
1e00: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72  4 are the prefer
1e10: 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74  red type definit
1e20: 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  ions..** The sql
1e30: 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  ite_int64 and sq
1e40: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65  lite_uint64 type
1e50: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  s are supported 
1e60: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
1e70: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
1e80: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  nly..**.** INVAR
1e90: 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
1ea0: 30 32 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  0201} The [sqlit
1eb0: 65 5f 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71  e_int64] and [sq
1ec0: 6c 69 74 65 33 5f 69 6e 74 36 34 5d 20 74 79 70  lite3_int64] typ
1ed0: 65 20 73 68 61 6c 6c 20 73 70 65 63 69 66 79 0a  e shall specify.
1ee0: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 36 34  **          a 64
1ef0: 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
1f00: 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32  ger..**.** {H102
1f10: 30 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 5f  02} The [sqlite_
1f20: 75 69 6e 74 36 34 5d 20 61 6e 64 20 5b 73 71 6c  uint64] and [sql
1f30: 69 74 65 33 5f 75 69 6e 74 36 34 5d 20 74 79 70  ite3_uint64] typ
1f40: 65 20 73 68 61 6c 6c 20 73 70 65 63 69 66 79 0a  e shall specify.
1f50: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 36 34  **          a 64
1f60: 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
1f70: 74 65 67 65 72 2e 0a 2a 2f 0a 23 69 66 64 65 66  teger..*/.#ifdef
1f80: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
1f90: 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c  PE.  typedef SQL
1fa0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
1fb0: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
1fc0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
1fd0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
1fe0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
1ff0: 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f  .#elif defined(_
2000: 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69  MSC_VER) || defi
2010: 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f  ned(__BORLANDC__
2020: 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e  ).  typedef __in
2030: 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  t64 sqlite_int64
2040: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
2050: 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c  gned __int64 sql
2060: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73  ite_uint64;.#els
2070: 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67  e.  typedef long
2080: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2090: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
20a0: 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20  f unsigned long 
20b0: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
20c0: 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74  uint64;.#endif.t
20d0: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e  ypedef sqlite_in
20e0: 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t64 sqlite3_int6
20f0: 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  4;.typedef sqlit
2100: 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e_uint64 sqlite3
2110: 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20  _uint64;../*.** 
2120: 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72  If compiling for
2130: 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61   a processor tha
2140: 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67  t lacks floating
2150: 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a   point support,.
2160: 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e  ** substitute in
2170: 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69  teger for floati
2180: 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66  ng-point..*/.#if
2190: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
21a0: 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23  FLOATING_POINT.#
21b0: 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73   define double s
21c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e  qlite3_int64.#en
21d0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
21e0: 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44  REF: Closing A D
21f0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2200: 6f 6e 20 7b 48 31 32 30 31 30 7d 20 3c 53 33 30  on {H12010} <S30
2210: 31 30 30 3e 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a  100><S40200>.**.
2220: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
2230: 69 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  is the destructo
2240: 72 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  r for the [sqlit
2250: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  e3] object..**.*
2260: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
2270: 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66  hould [sqlite3_f
2280: 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
2290: 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  ze] all [prepare
22a0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a  d statements].**
22b0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c   and [sqlite3_bl
22c0: 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65  ob_close | close
22d0: 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64  ] all [BLOB hand
22e0: 6c 65 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20  les] associated 
22f0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  with.** the [sql
2300: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69  ite3] object pri
2310: 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67  or to attempting
2320: 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62   to close the ob
2330: 6a 65 63 74 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  ject..** The [sq
2340: 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
2350: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  )] interface can
2360: 20 62 65 20 75 73 65 64 20 74 6f 20 6c 6f 63 61   be used to loca
2370: 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70 72 65 70 61  te all.** [prepa
2380: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
2390: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
23a0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
23b0: 65 63 74 69 6f 6e 5d 20 69 66 20 64 65 73 69 72  ection] if desir
23c0: 65 64 2e 0a 2a 2a 20 54 79 70 69 63 61 6c 20 63  ed..** Typical c
23d0: 6f 64 65 20 6d 69 67 68 74 20 6c 6f 6f 6b 20 6c  ode might look l
23e0: 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
23f0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
2400: 3e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  >.** sqlite3_stm
2410: 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a 20 77 68 69  t *pStmt;.** whi
2420: 6c 65 28 20 28 70 53 74 6d 74 20 3d 20 73 71 6c  le( (pStmt = sql
2430: 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 64  ite3_next_stmt(d
2440: 62 2c 20 30 29 29 21 3d 30 20 29 7b 0a 2a 2a 20  b, 0))!=0 ){.** 
2450: 26 6e 62 73 70 3b 20 20 20 73 71 6c 69 74 65 33  &nbsp;   sqlite3
2460: 5f 66 69 6e 61 6c 69 7a 65 28 70 53 74 6d 74 29  _finalize(pStmt)
2470: 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f 70 72 65 3e  ;.** }.** </pre>
2480: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
2490: 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
24a0: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
24b0: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
24c0: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
24d0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
24e0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
24f0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2500: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2510: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31  TS:.**.** {H1201
2520: 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  1} A successful 
2530: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2540: 5f 63 6c 6f 73 65 28 43 29 5d 20 73 68 61 6c 6c  _close(C)] shall
2550: 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a 20   destroy the.** 
2560: 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
2570: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
2580: 62 6a 65 63 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b  bject C..**.** {
2590: 48 31 32 30 31 32 7d 20 41 20 73 75 63 63 65 73  H12012} A succes
25a0: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
25b0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
25c0: 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c  shall return SQL
25d0: 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ITE_OK..**.** {H
25e0: 31 32 30 31 33 7d 20 41 20 73 75 63 63 65 73 73  12013} A success
25f0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
2600: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73  ite3_close(C)] s
2610: 68 61 6c 6c 20 72 65 6c 65 61 73 65 20 61 6c 6c  hall release all
2620: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d  .**          mem
2630: 6f 72 79 20 61 6e 64 20 73 79 73 74 65 6d 20 72  ory and system r
2640: 65 73 6f 75 72 63 65 73 20 61 73 73 6f 63 69 61  esources associa
2650: 74 65 64 20 77 69 74 68 20 5b 64 61 74 61 62 61  ted with [databa
2660: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
2670: 2a 20 20 20 20 20 20 20 20 20 20 43 2e 0a 2a 2a  *          C..**
2680: 0a 2a 2a 20 7b 48 31 32 30 31 34 7d 20 41 20 63  .** {H12014} A c
2690: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
26a0: 63 6c 6f 73 65 28 43 29 5d 20 6f 6e 20 61 20 5b  close(C)] on a [
26b0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26c0: 69 6f 6e 5d 20 43 20 74 68 61 74 0a 2a 2a 20 20  ion] C that.**  
26d0: 20 20 20 20 20 20 20 20 68 61 73 20 6f 6e 65 20          has one 
26e0: 6f 72 20 6d 6f 72 65 20 6f 70 65 6e 20 5b 70 72  or more open [pr
26f0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2700: 73 5d 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69  s] shall fail wi
2710: 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  th.**          a
2720: 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
2730: 65 72 72 6f 72 20 63 6f 64 65 2e 0a 2a 2a 0a 2a  error code..**.*
2740: 2a 20 7b 48 31 32 30 31 35 7d 20 41 20 63 61 6c  * {H12015} A cal
2750: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  l to [sqlite3_cl
2760: 6f 73 65 28 43 29 5d 20 77 68 65 72 65 20 43 20  ose(C)] where C 
2770: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2780: 72 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  r shall.**      
2790: 20 20 20 20 72 65 74 75 72 6e 20 53 51 4c 49 54      return SQLIT
27a0: 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  E_OK..**.** {H12
27b0: 30 31 39 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74  019} When [sqlit
27c0: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 69 73 20  e3_close(C)] is 
27d0: 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 5b 64 61  invoked on a [da
27e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
27f0: 6e 5d 20 43 0a 2a 2a 20 20 20 20 20 20 20 20 20  n] C.**         
2800: 20 74 68 61 74 20 68 61 73 20 61 20 70 65 6e 64   that has a pend
2810: 69 6e 67 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  ing transaction,
2820: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
2830: 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20 20 20   shall be.**    
2840: 20 20 20 20 20 20 72 6f 6c 6c 65 64 20 62 61 63        rolled bac
2850: 6b 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54  k..**.** ASSUMPT
2860: 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  IONS:.**.** {A12
2870: 30 31 36 7d 20 54 68 65 20 43 20 70 61 72 61 6d  016} The C param
2880: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
2890: 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75 73 74 20  _close(C)] must 
28a0: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
28b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69  .**          poi
28c0: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  nter or an [sqli
28d0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  te3] object poin
28e0: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ter obtained.** 
28f0: 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 5b 73           from [s
2900: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2910: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2920: 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
2930: 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
2940: 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20  _v2()], and not 
2950: 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65  previously close
2960: 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2970: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20  3_close(sqlite3 
2980: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
2990: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
29a0: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
29b0: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
29c0: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
29d0: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
29e0: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
29f0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
2a00: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
2a10: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
2a20: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
2a30: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
2a40: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
2a50: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2a60: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
2a70: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
2a80: 74 65 72 66 61 63 65 20 7b 48 31 32 31 30 30 7d  terface {H12100}
2a90: 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10000>.**.** 
2aa0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
2ab0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2ac0: 61 20 63 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79  a convenient way
2ad0: 20 6f 66 20 72 75 6e 6e 69 6e 67 20 6f 6e 65 20   of running one 
2ae0: 6f 72 20 6d 6f 72 65 0a 2a 2a 20 53 51 4c 20 73  or more.** SQL s
2af0: 74 61 74 65 6d 65 6e 74 73 20 77 69 74 68 6f 75  tatements withou
2b00: 74 20 68 61 76 69 6e 67 20 74 6f 20 77 72 69 74  t having to writ
2b10: 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64  e a lot of C cod
2b20: 65 2e 20 20 54 68 65 20 55 54 46 2d 38 20 65 6e  e.  The UTF-8 en
2b30: 63 6f 64 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  coded.** SQL sta
2b40: 74 65 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73  tements are pass
2b50: 65 64 20 69 6e 20 61 73 20 74 68 65 20 73 65 63  ed in as the sec
2b60: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
2b70: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2e   sqlite3_exec().
2b80: 0a 2a 2a 20 54 68 65 20 73 74 61 74 65 6d 65 6e  .** The statemen
2b90: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
2ba0: 20 6f 6e 65 20 62 79 20 6f 6e 65 20 75 6e 74 69   one by one unti
2bb0: 6c 20 65 69 74 68 65 72 20 61 6e 20 65 72 72 6f  l either an erro
2bc0: 72 20 6f 72 0a 2a 2a 20 61 6e 20 69 6e 74 65 72  r or.** an inter
2bd0: 72 75 70 74 20 69 73 20 65 6e 63 6f 75 6e 74 65  rupt is encounte
2be0: 72 65 64 2c 20 6f 72 20 75 6e 74 69 6c 20 74 68  red, or until th
2bf0: 65 79 20 61 72 65 20 61 6c 6c 20 64 6f 6e 65 2e  ey are all done.
2c00: 20 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65    The 3rd parame
2c10: 74 65 72 0a 2a 2a 20 69 73 20 61 6e 20 6f 70 74  ter.** is an opt
2c20: 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 74  ional callback t
2c30: 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hat is invoked o
2c40: 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77  nce for each row
2c50: 20 6f 66 20 61 6e 79 20 71 75 65 72 79 0a 2a 2a   of any query.**
2c60: 20 72 65 73 75 6c 74 73 20 70 72 6f 64 75 63 65   results produce
2c70: 64 20 62 79 20 74 68 65 20 53 51 4c 20 73 74 61  d by the SQL sta
2c80: 74 65 6d 65 6e 74 73 2e 20 20 54 68 65 20 35 74  tements.  The 5t
2c90: 68 20 70 61 72 61 6d 65 74 65 72 20 74 65 6c 6c  h parameter tell
2ca0: 73 20 77 68 65 72 65 0a 2a 2a 20 74 6f 20 77 72  s where.** to wr
2cb0: 69 74 65 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  ite any error me
2cc0: 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ssages..**.** Th
2cd0: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
2ce0: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
2cf0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
2d00: 6d 65 74 65 72 20 69 73 20 68 65 6c 64 0a 2a 2a  meter is held.**
2d10: 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   in memory obtai
2d20: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2d30: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f  3_malloc()].  To
2d40: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20   avoid a memory 
2d50: 6c 65 61 6b 2c 0a 2a 2a 20 74 68 65 20 63 61 6c  leak,.** the cal
2d60: 6c 69 6e 67 20 61 70 70 6c 69 63 61 74 69 6f 6e  ling application
2d70: 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 5b 73 71   should call [sq
2d80: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
2d90: 20 61 6e 79 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   any error.** me
2da0: 73 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 74  ssage returned t
2db0: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
2dc0: 61 72 61 6d 65 74 65 72 20 77 68 65 6e 20 69 74  arameter when it
2dd0: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
2de0: 69 6e 67 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  ing.** the error
2df0: 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
2e00: 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2e10: 6d 65 6e 74 20 69 6e 20 74 68 65 20 32 6e 64 20  ment in the 2nd 
2e20: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
2e30: 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74  L or an empty st
2e40: 72 69 6e 67 0a 2a 2a 20 6f 72 20 61 20 73 74 72  ring.** or a str
2e50: 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6f  ing containing o
2e60: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61  nly whitespace a
2e70: 6e 64 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  nd comments, the
2e80: 6e 20 6e 6f 20 53 51 4c 0a 2a 2a 20 73 74 61 74  n no SQL.** stat
2e90: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75  ements are evalu
2ea0: 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74  ated and the dat
2eb0: 61 62 61 73 65 20 69 73 20 6e 6f 74 20 63 68 61  abase is not cha
2ec0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nged..**.** The 
2ed0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
2ee0: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
2ef0: 65 6d 65 6e 74 65 64 20 69 6e 20 74 65 72 6d 73  emented in terms
2f00: 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
2f10: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
2f20: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
2f30: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69   and [sqlite3_fi
2f40: 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68  nalize()]..** Th
2f50: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
2f60: 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
2f70: 74 68 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74  thing to the dat
2f80: 61 62 61 73 65 20 74 68 61 74 20 63 61 6e 6e 6f  abase that canno
2f90: 74 20 62 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20  t be done.** by 
2fa0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2fb0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2fc0: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
2fd0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2fe0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
2ff0: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
3000: 31 30 31 7d 20 41 20 73 75 63 63 65 73 73 66 75  101} A successfu
3010: 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  l invocation of 
3020: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c  [sqlite3_exec(D,
3030: 53 2c 43 2c 41 2c 45 29 5d 0a 2a 2a 20 20 20 20  S,C,A,E)].**    
3040: 20 20 20 20 20 20 73 68 61 6c 6c 20 73 65 71 75        shall sequ
3050: 65 6e 74 69 61 6c 6c 79 20 65 76 61 6c 75 61 74  entially evaluat
3060: 65 20 61 6c 6c 20 6f 66 20 74 68 65 20 55 54 46  e all of the UTF
3070: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 20  -8 encoded,.**  
3080: 20 20 20 20 20 20 20 20 73 65 6d 69 63 6f 6c 6f          semicolo
3090: 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20  n-separated SQL 
30a0: 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
30b0: 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
30c0: 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  d.**          st
30d0: 72 69 6e 67 20 53 20 77 69 74 68 69 6e 20 74 68  ring S within th
30e0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
30f0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
3100: 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
3110: 7b 48 31 32 31 30 32 7d 20 49 66 20 74 68 65 20  {H12102} If the 
3120: 53 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  S parameter to [
3130: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53  sqlite3_exec(D,S
3140: 2c 43 2c 41 2c 45 29 5d 20 69 73 20 4e 55 4c 4c  ,C,A,E)] is NULL
3150: 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
3160: 20 20 74 68 65 20 61 63 74 69 6f 6e 73 20 6f 66    the actions of
3170: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 73   the interface s
3180: 68 61 6c 6c 20 62 65 20 74 68 65 20 73 61 6d 65  hall be the same
3190: 20 61 73 20 69 66 20 74 68 65 0a 2a 2a 20 20 20   as if the.**   
31a0: 20 20 20 20 20 20 20 53 20 70 61 72 61 6d 65 74         S paramet
31b0: 65 72 20 77 65 72 65 20 61 6e 20 65 6d 70 74 79  er were an empty
31c0: 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
31d0: 48 31 32 31 30 34 7d 20 54 68 65 20 72 65 74 75  H12104} The retu
31e0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c  rn value of [sql
31f0: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61  ite3_exec()] sha
3200: 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 4f 4b  ll be [SQLITE_OK
3210: 5d 20 69 66 20 61 6c 6c 0a 2a 2a 20 20 20 20 20  ] if all.**     
3220: 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65       SQL stateme
3230: 6e 74 73 20 72 75 6e 20 73 75 63 63 65 73 73 66  nts run successf
3240: 75 6c 6c 79 20 61 6e 64 20 74 6f 20 63 6f 6d 70  ully and to comp
3250: 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48  letion..**.** {H
3260: 31 32 31 30 35 7d 20 54 68 65 20 72 65 74 75 72  12105} The retur
3270: 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  n value of [sqli
3280: 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68 61 6c  te3_exec()] shal
3290: 6c 20 62 65 20 61 6e 20 61 70 70 72 6f 70 72 69  l be an appropri
32a0: 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ate.**          
32b0: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
32c0: 63 6f 64 65 5d 20 69 66 20 61 6e 79 20 53 51 4c  code] if any SQL
32d0: 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 73   statement fails
32e0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30 37 7d  ..**.** {H12107}
32f0: 20 49 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   If one or more 
3300: 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  of the SQL state
3310: 6d 65 6e 74 73 20 68 61 6e 64 65 64 20 74 6f 20  ments handed to 
3320: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3330: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
3340: 75 72 6e 20 72 65 73 75 6c 74 73 20 61 6e 64 20  urn results and 
3350: 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
3360: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  r is not NULL, t
3370: 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
3380: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
3390: 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20  ction specified 
33a0: 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  by the 3rd param
33b0: 65 74 65 72 20 73 68 61 6c 6c 20 62 65 0a 2a 2a  eter shall be.**
33c0: 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 6b 65            invoke
33d0: 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
33e0: 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 0a 2a  row of result..*
33f0: 2a 0a 2a 2a 20 7b 48 31 32 31 31 30 7d 20 49 66  *.** {H12110} If
3400: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
3410: 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
3420: 20 76 61 6c 75 65 20 74 68 65 6e 20 5b 73 71 6c   value then [sql
3430: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20  ite3_exec()].** 
3440: 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 61           shall a
3450: 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
3460: 74 65 6d 65 6e 74 20 69 74 20 69 73 20 63 75 72  tement it is cur
3470: 72 65 6e 74 6c 79 20 65 76 61 6c 75 61 74 69 6e  rently evaluatin
3480: 67 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  g,.**          s
3490: 6b 69 70 20 61 6c 6c 20 73 75 62 73 65 71 75 65  kip all subseque
34a0: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  nt SQL statement
34b0: 73 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  s, and return [S
34c0: 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a  QLITE_ABORT]..**
34d0: 0a 2a 2a 20 7b 48 31 32 31 31 33 7d 20 54 68 65  .** {H12113} The
34e0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
34f0: 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
3500: 70 61 73 73 20 69 74 73 20 34 74 68 20 70 61 72  pass its 4th par
3510: 61 6d 65 74 65 72 20 74 68 72 6f 75 67 68 0a 2a  ameter through.*
3520: 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68  *          as th
3530: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
3540: 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e  of the callback.
3550: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 36 7d 20  .**.** {H12116} 
3560: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  The [sqlite3_exe
3570: 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61  c()] routine sha
3580: 6c 6c 20 73 65 74 20 74 68 65 20 32 6e 64 20 70  ll set the 2nd p
3590: 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a  arameter of its.
35a0: 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c  **          call
35b0: 62 61 63 6b 20 74 6f 20 62 65 20 74 68 65 20 6e  back to be the n
35c0: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
35d0: 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
35e0: 72 6f 77 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  row of.**       
35f0: 20 20 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a 2a 2a     result..**.**
3600: 20 7b 48 31 32 31 31 39 7d 20 54 68 65 20 5b 73   {H12119} The [s
3610: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72  qlite3_exec()] r
3620: 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74  outine shall set
3630: 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
3640: 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20  er of its.**    
3650: 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74        callback t
3660: 6f 20 62 65 20 61 6e 20 61 72 72 61 79 20 6f 66  o be an array of
3670: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3680: 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65  ings holding the
3690: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
36a0: 75 65 73 20 66 6f 72 20 65 61 63 68 20 63 6f 6c  ues for each col
36b0: 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
36c0: 6e 74 20 72 65 73 75 6c 74 20 73 65 74 20 72 6f  nt result set ro
36d0: 77 20 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  w as.**         
36e0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
36f0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
3700: 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ext()]..**.** {H
3710: 31 32 31 32 32 7d 20 54 68 65 20 5b 73 71 6c 69  12122} The [sqli
3720: 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f 75 74  te3_exec()] rout
3730: 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68  ine shall set th
3740: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
3750: 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20  of its.**       
3760: 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62     callback to b
3770: 65 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  e an array of po
3780: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3790: 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a 2a 2a  s holding the.**
37a0: 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 73 20            names 
37b0: 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
37c0: 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66 72  s as obtained fr
37d0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
37e0: 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a  mn_name()]..**.*
37f0: 2a 20 7b 48 31 32 31 32 35 7d 20 49 66 20 74 68  * {H12125} If th
3800: 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
3810: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
3820: 28 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ()] is NULL then
3830: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
3840: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68  lite3_exec()] sh
3850: 61 6c 6c 20 73 69 6c 65 6e 74 6c 79 20 64 69 73  all silently dis
3860: 63 61 72 64 20 71 75 65 72 79 20 72 65 73 75 6c  card query resul
3870: 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33  ts..**.** {H1213
3880: 31 7d 20 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  1} If an error o
3890: 63 63 75 72 73 20 77 68 69 6c 65 20 70 61 72 73  ccurs while pars
38a0: 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  ing or evaluatin
38b0: 67 20 61 6e 79 20 6f 66 20 74 68 65 20 53 51 4c  g any of the SQL
38c0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 61  .**          sta
38d0: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 53  tements in the S
38e0: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
38f0: 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c  qlite3_exec(D,S,
3900: 43 2c 41 2c 45 29 5d 20 61 6e 64 20 69 66 0a 2a  C,A,E)] and if.*
3910: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 45  *          the E
3920: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
3930: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 73 71  t NULL, then [sq
3940: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68  lite3_exec()] sh
3950: 61 6c 6c 20 73 74 6f 72 65 0a 2a 2a 20 20 20 20  all store.**    
3960: 20 20 20 20 20 20 69 6e 20 2a 45 20 61 6e 20 61        in *E an a
3970: 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
3980: 20 6d 65 73 73 61 67 65 20 77 72 69 74 74 65 6e   message written
3990: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
39a0: 61 69 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  ained.**        
39b0: 20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f    from [sqlite3_
39c0: 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a  malloc()]..**.**
39d0: 20 7b 48 31 32 31 33 34 7d 20 54 68 65 20 5b 73   {H12134} The [s
39e0: 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c  qlite3_exec(D,S,
39f0: 43 2c 41 2c 45 29 5d 20 72 6f 75 74 69 6e 65 20  C,A,E)] routine 
3a00: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 76 61  shall set the va
3a10: 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  lue of.**       
3a20: 20 20 20 2a 45 20 74 6f 20 4e 55 4c 4c 20 69 66     *E to NULL if
3a30: 20 45 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61   E is not NULL a
3a40: 6e 64 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  nd there are no 
3a50: 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  errors..**.** {H
3a60: 31 32 31 33 37 7d 20 54 68 65 20 5b 73 71 6c 69  12137} The [sqli
3a70: 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41  te3_exec(D,S,C,A
3a80: 2c 45 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68  ,E)] function sh
3a90: 61 6c 6c 20 73 65 74 20 74 68 65 20 5b 65 72 72  all set the [err
3aa0: 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 20 20 20 20  or code].**     
3ab0: 20 20 20 20 20 61 6e 64 20 6d 65 73 73 61 67 65       and message
3ac0: 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20   accessible via 
3ad0: 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
3ae0: 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
3af0: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
3b00: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
3b10: 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a  3_errmsg16()]..*
3b20: 2a 0a 2a 2a 20 7b 48 31 32 31 33 38 7d 20 49 66  *.** {H12138} If
3b30: 20 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72   the S parameter
3b40: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
3b50: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73  c(D,S,C,A,E)] is
3b60: 20 4e 55 4c 4c 20 6f 72 20 61 6e 0a 2a 2a 20 20   NULL or an.**  
3b70: 20 20 20 20 20 20 20 20 65 6d 70 74 79 20 73 74          empty st
3b80: 72 69 6e 67 20 6f 72 20 63 6f 6e 74 61 69 6e 73  ring or contains
3b90: 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74   nothing other t
3ba0: 68 61 6e 20 77 68 69 74 65 73 70 61 63 65 2c 20  han whitespace, 
3bb0: 63 6f 6d 6d 65 6e 74 73 2c 0a 2a 2a 20 20 20 20  comments,.**    
3bc0: 20 20 20 20 20 20 61 6e 64 2f 6f 72 20 73 65 6d        and/or sem
3bd0: 69 63 6f 6c 6f 6e 73 2c 20 74 68 65 6e 20 72 65  icolons, then re
3be0: 73 75 6c 74 73 20 6f 66 20 5b 73 71 6c 69 74 65  sults of [sqlite
3bf0: 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a  3_errcode()],.**
3c00: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
3c10: 65 33 5f 65 72 72 6d 73 67 28 29 5d 2c 20 61 6e  e3_errmsg()], an
3c20: 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d [sqlite3_errms
3c30: 67 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  g16()].**       
3c40: 20 20 20 73 68 61 6c 6c 20 72 65 73 65 74 20 74     shall reset t
3c50: 6f 20 69 6e 64 69 63 61 74 65 20 6e 6f 20 65 72  o indicate no er
3c60: 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55  rors..**.** ASSU
3c70: 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  MPTIONS:.**.** {
3c80: 41 31 32 31 34 31 7d 20 54 68 65 20 66 69 72 73  A12141} The firs
3c90: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
3ca0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3cb0: 6d 75 73 74 20 62 65 20 61 6e 20 76 61 6c 69 64  must be an valid
3cc0: 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 20 20 20   and open.**    
3cd0: 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
3ce0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  connection]..**.
3cf0: 2a 2a 20 7b 41 31 32 31 34 32 7d 20 54 68 65 20  ** {A12142} The 
3d00: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3d10: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  ion must not be 
3d20: 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20  closed while.** 
3d30: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
3d40: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e  3_exec()] is run
3d50: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  ning..**.** {A12
3d60: 31 34 33 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67  143} The calling
3d70: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
3d80: 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 72   use [sqlite3_fr
3d90: 65 65 28 29 5d 20 74 6f 20 66 72 65 65 0a 2a 2a  ee()] to free.**
3da0: 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6d 65            the me
3db0: 6d 6f 72 79 20 74 68 61 74 20 2a 65 72 72 6d 73  mory that *errms
3dc0: 67 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  g is left pointi
3dd0: 6e 67 20 61 74 20 6f 6e 63 65 20 74 68 65 20 65  ng at once the e
3de0: 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rror.**         
3df0: 20 6d 65 73 73 61 67 65 20 69 73 20 6e 6f 20 6c   message is no l
3e00: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
3e10: 0a 2a 2a 20 7b 41 31 32 31 34 35 7d 20 54 68 65  .** {A12145} The
3e20: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
3e30: 65 78 74 20 69 6e 20 74 68 65 20 32 6e 64 20 70  ext in the 2nd p
3e40: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
3e50: 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a 2a 20  ite3_exec()].** 
3e60: 20 20 20 20 20 20 20 20 20 6d 75 73 74 20 72 65           must re
3e70: 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 77  main unchanged w
3e80: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 65 78  hile [sqlite3_ex
3e90: 65 63 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  ec()] is running
3ea0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
3eb0: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
3ec0: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
3ed0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ee0: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
3ef0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
3f00: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
3f10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3f20: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
3f30: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
3f40: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
3f50: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3f60: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
3f70: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
3f80: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
3f90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fa0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fb0: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
3fc0: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
3fd0: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
3fe0: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
3ff0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4000: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
4010: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
4020: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4030: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48   Result Codes {H
4040: 31 30 32 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a  10210} <S10700>.
4050: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
4060: 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f  ITE_OK {error co
4070: 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73  de} {error codes
4080: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
4090: 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65  result code} {re
40a0: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a  sult codes}.**.*
40b0: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75  * Many SQLite fu
40c0: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61  nctions return a
40d0: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74  n integer result
40e0: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73   code from the s
40f0: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65  et shown.** here
4100: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64   in order to ind
4110: 69 63 61 74 65 73 20 73 75 63 63 65 73 73 20 6f  icates success o
4120: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
4130: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
4140: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
4150: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
4160: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
4170: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c  * See also: [SQL
4180: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c  ITE_IOERR_READ |
4190: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
41a0: 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69   codes].*/.#defi
41b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20  ne SQLITE_OK    
41c0: 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75         0   /* Su
41d0: 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20  ccessful result 
41e0: 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d  */./* beginning-
41f0: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4200: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4210: 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20  _ERROR        1 
4220: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f    /* SQL error o
4230: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61  r missing databa
4240: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
4250: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20  LITE_INTERNAL   
4260: 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61    2   /* Interna
4270: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  l logic error in
4280: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69   SQLite */.#defi
4290: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20  ne SQLITE_PERM  
42a0: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63         3   /* Ac
42b0: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20  cess permission 
42c0: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
42d0: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20  e SQLITE_ABORT  
42e0: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c        4   /* Cal
42f0: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
4300: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74  quested an abort
4310: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4320: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20  TE_BUSY         
4330: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  5   /* The datab
4340: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b  ase file is lock
4350: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4360: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20  LITE_LOCKED     
4370: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65    6   /* A table
4380: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
4390: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
43a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d  efine SQLITE_NOM
43b0: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  EM        7   /*
43c0: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c   A malloc() fail
43d0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
43e0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20  LITE_READONLY   
43f0: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74    8   /* Attempt
4400: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64   to write a read
4410: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f  only database */
4420: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4430: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20  INTERRUPT    9  
4440: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65   /* Operation te
4450: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69  rminated by sqli
4460: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a  te3_interrupt()*
4470: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4480: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20  _IOERR       10 
4490: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f    /* Some kind o
44a0: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72  f disk I/O error
44b0: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65   occurred */.#de
44c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
44d0: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20  UPT     11   /* 
44e0: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73  The database dis
44f0: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f  k image is malfo
4500: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rmed */.#define 
4510: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
4520: 20 20 20 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55     12   /* NOT U
4530: 53 45 44 2e 20 54 61 62 6c 65 20 6f 72 20 72 65  SED. Table or re
4540: 63 6f 72 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a  cord not found *
4550: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4560: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
4570: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
4580: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
4590: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
45a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45b0: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
45c0: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
45d0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
45e0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
45f0: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
4600: 20 20 20 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20      15   /* NOT 
4610: 55 53 45 44 2e 20 44 61 74 61 62 61 73 65 20 6c  USED. Database l
4620: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72  ock protocol err
4630: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4640: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20  LITE_EMPTY      
4650: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   16   /* Databas
4660: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64  e is empty */.#d
4670: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
4680: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
4690: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
46a0: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
46b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
46c0: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
46d0: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
46e0: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
46f0: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
4700: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
4710: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
4720: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
4730: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
4740: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4750: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
4760: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
4770: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
4780: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4790: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
47a0: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
47b0: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
47c0: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
47d0: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
47e0: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
47f0: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4800: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4810: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4820: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
4830: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
4840: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4850: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
4860: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74  /* Auxiliary dat
4870: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72  abase format err
4880: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4890: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20  LITE_RANGE      
48a0: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72   25   /* 2nd par
48b0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
48c0: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61  3_bind out of ra
48d0: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge */.#define S
48e0: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20  QLITE_NOTADB    
48f0: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f    26   /* File o
4900: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f  pened that is no
4910: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
4920: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4930: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20  ITE_ROW         
4940: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  100  /* sqlite3_
4950: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68  step() has anoth
4960: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a  er row ready */.
4970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
4980: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20  ONE        101  
4990: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
49a0: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  ) has finished e
49b0: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65  xecuting */./* e
49c0: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  nd-of-error-code
49d0: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s */../*.** CAPI
49e0: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52  3REF: Extended R
49f0: 65 73 75 6c 74 20 43 6f 64 65 73 20 7b 48 31 30  esult Codes {H10
4a00: 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  220} <S10700>.**
4a10: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4a20: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d  nded error code}
4a30: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
4a40: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f   codes}.** KEYWO
4a50: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4a60: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74  esult code} {ext
4a70: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4a80: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
4a90: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4aa0: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4ab0: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4ac0: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4ad0: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
4ae0: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
4af0: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
4b00: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
4b10: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
4b20: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
4b30: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
4b40: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
4b50: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
4b60: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
4b70: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
4b80: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
4b90: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
4ba0: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4bb0: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4bc0: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4bd0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
4be0: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
4bf0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4c00: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4c10: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
4c20: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
4c30: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4c40: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4c50: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4c60: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
4c70: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
4c80: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4c90: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4ca0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4cb0: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4cc0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4cd0: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
4ce0: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a  des()] API..**.*
4cf0: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
4d00: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
4d10: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4d20: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a  e listed here..*
4d30: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74  * One may expect
4d40: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
4d50: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4d60: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70  odes will be exp
4d70: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65  and.** over time
4d80: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
4d90: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72   uses extended r
4da0: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75  esult codes shou
4db0: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20  ld expect.** to 
4dc0: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63  see new result c
4dd0: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  odes in future r
4de0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
4df0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  e..**.** The SQL
4e00: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f  ITE_OK result co
4e10: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65  de will never be
4e20: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77   extended.  It w
4e30: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  ill always.** be
4e40: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a   exactly zero..*
4e50: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
4e60: 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 33 7d 20  .**.** {H10223} 
4e70: 54 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d  The symbolic nam
4e80: 65 20 66 6f 72 20 61 6e 20 65 78 74 65 6e 64 65  e for an extende
4e90: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 73 68  d result code sh
4ea0: 61 6c 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  all contains.** 
4eb0: 20 20 20 20 20 20 20 20 20 61 20 72 65 6c 61 74           a relat
4ec0: 65 64 20 70 72 69 6d 61 72 79 20 72 65 73 75 6c  ed primary resul
4ed0: 74 20 63 6f 64 65 20 61 73 20 61 20 70 72 65 66  t code as a pref
4ee0: 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32  ix..**.** {H1022
4ef0: 34 7d 20 50 72 69 6d 61 72 79 20 72 65 73 75 6c  4} Primary resul
4f00: 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61  t code names sha
4f10: 6c 6c 20 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e  ll contain a sin
4f20: 67 6c 65 20 22 5f 22 20 63 68 61 72 61 63 74 65  gle "_" characte
4f30: 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 32 35  r..**.** {H10225
4f40: 7d 20 45 78 74 65 6e 64 65 64 20 72 65 73 75 6c  } Extended resul
4f50: 74 20 63 6f 64 65 20 6e 61 6d 65 73 20 73 68 61  t code names sha
4f60: 6c 6c 20 63 6f 6e 74 61 69 6e 20 74 77 6f 20 6f  ll contain two o
4f70: 72 20 6d 6f 72 65 20 22 5f 22 20 63 68 61 72 61  r more "_" chara
4f80: 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  cters..**.** {H1
4f90: 30 32 32 36 7d 20 54 68 65 20 6e 75 6d 65 72 69  0226} The numeri
4fa0: 63 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 65 78  c value of an ex
4fb0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4fc0: 64 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e  de shall contain
4fd0: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
4fe0: 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f   numeric value o
4ff0: 66 20 69 74 73 20 63 6f 72 72 65 73 70 6f 6e 64  f its correspond
5000: 69 6e 67 20 70 72 69 6d 61 72 79 20 72 65 73 75  ing primary resu
5010: 6c 74 20 63 6f 64 65 20 69 6e 0a 2a 2a 20 20 20  lt code in.**   
5020: 20 20 20 20 20 20 20 69 74 73 20 6c 65 61 73 74         its least
5030: 20 73 69 67 6e 69 66 69 63 61 6e 74 20 38 20 62   significant 8 b
5040: 69 74 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  its..*/.#define 
5050: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
5060: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  D              (
5070: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5080: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5090: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
50a0: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53  T_READ        (S
50b0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
50c0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
50d0: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45  LITE_IOERR_WRITE
50e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
50f0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
5100: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5110: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
5120: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5130: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c  ITE_IOERR | (4<<
5140: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5150: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59  TE_IOERR_DIR_FSY
5160: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
5170: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
5180: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5190: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
51a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51b0: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29  E_IOERR | (6<<8)
51c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51d0: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20  _IOERR_FSTAT    
51e0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
51f0: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
5200: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5210: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
5220: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5230: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a  IOERR | (8<<8)).
5240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5250: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20  OERR_RDLOCK     
5260: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5270: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
5280: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5290: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
52a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
52b0: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23  ERR | (10<<8)).#
52c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52d0: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20  ERR_BLOCKED     
52e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
52f0: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23  ERR | (11<<8)).#
5300: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5310: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ERR_NOMEM       
5320: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5330: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23  ERR | (12<<8)).#
5340: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5350: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20  ERR_ACCESS      
5360: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5370: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23  ERR | (13<<8)).#
5380: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5390: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45  ERR_CHECKRESERVE
53a0: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f  DLOCK (SQLITE_IO
53b0: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 0a  ERR | (14<<8))..
53c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
53d0: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
53e0: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 20 7b  pen Operations {
53f0: 48 31 30 32 33 30 7d 20 3c 48 31 31 31 32 30 3e  H10230} <H11120>
5400: 20 3c 48 31 32 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H12700>.**.** 
5410: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
5420: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
5430: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20  r use in the.** 
5440: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
5450: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
5460: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
5470: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65  ce and.** in the
5480: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
5490: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
54a0: 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  od of the.** [sq
54b0: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
54c0: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
54d0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
54e0: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
54f0: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
5500: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
5510: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
5520: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
5530: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
5540: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5550: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51  00004.#define SQ
5560: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
5570: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
5580: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
5590: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
55a0: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
55b0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
55c0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
55d0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
55e0: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
55f0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
5600: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
5610: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
5620: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
5630: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
5640: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00400.#define SQ
5650: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
5660: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
5670: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
5680: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
5690: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
56a0: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
56b0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
56c0: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
56d0: 30 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  02000.#define SQ
56e0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
56f0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
5700: 30 34 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  04000.#define SQ
5710: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
5720: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
5730: 30 38 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  08000../*.** CAP
5740: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
5750: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 7b 48  aracteristics {H
5760: 31 30 32 34 30 7d 20 3c 48 31 31 31 32 30 3e 0a  10240} <H11120>.
5770: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
5780: 65 43 61 70 61 62 69 6c 69 74 69 65 73 20 6d 65  eCapabilities me
5790: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
57a0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
57b0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
57c0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
57d0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
57e0: 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20  of the these.** 
57f0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
5800: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
5810: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
5820: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
5830: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
5840: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
5850: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
5860: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
5870: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
5880: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5890: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
58a0: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
58b0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
58c0: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
58d0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
58e0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
58f0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
5900: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
5910: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
5920: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
5930: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
5940: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
5950: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
5960: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
5970: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
5980: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5990: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
59a0: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
59b0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
59c0: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
59d0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
59e0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
59f0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
5a00: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
5a10: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
5a20: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
5a30: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
5a40: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
5a50: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
5a60: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
5a70: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
5a80: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
5a90: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
5aa0: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
5ab0: 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  e()..*/.#define 
5ac0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5ad0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 30 78 30  MIC          0x0
5ae0: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20  0000001.#define 
5af0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b00: 4d 49 43 35 31 32 20 20 20 20 20 20 20 30 78 30  MIC512       0x0
5b10: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
5b20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b30: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 30 78 30  MIC1K        0x0
5b40: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
5b50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b60: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 30 78 30  MIC2K        0x0
5b70: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
5b80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b90: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 30 78 30  MIC4K        0x0
5ba0: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
5bb0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5bc0: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 30 78 30  MIC8K        0x0
5bd0: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
5be0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5bf0: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 30 78 30  MIC16K       0x0
5c00: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
5c10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5c20: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 30 78 30  MIC32K       0x0
5c30: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
5c40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5c50: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 30 78 30  MIC64K       0x0
5c60: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20  0000100.#define 
5c70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
5c80: 45 5f 41 50 50 45 4e 44 20 20 20 20 20 30 78 30  E_APPEND     0x0
5c90: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
5ca0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
5cb0: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 30 78 30  UENTIAL      0x0
5cc0: 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a 2a 20 43  0000400../*.** C
5cd0: 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f  API3REF: File Lo
5ce0: 63 6b 69 6e 67 20 4c 65 76 65 6c 73 20 7b 48 31  cking Levels {H1
5cf0: 30 32 35 30 7d 20 3c 48 31 31 31 32 30 3e 20 3c  0250} <H11120> <
5d00: 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51  H11310>.**.** SQ
5d10: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66  Lite uses one of
5d20: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
5d30: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
5d40: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ond.** argument 
5d50: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65  to calls it make
5d60: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29  s to the xLock()
5d70: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d   and xUnlock() m
5d80: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20  ethods.** of an 
5d90: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
5da0: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ods] object..*/.
5db0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5dc0: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20  OCK_NONE        
5dd0: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
5de0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20  TE_LOCK_SHARED  
5df0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
5e00: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
5e10: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66  RVED      2.#def
5e20: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5e30: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a  PENDING       3.
5e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5e50: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20  OCK_EXCLUSIVE   
5e60: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    4../*.** CAPI3
5e70: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61  REF: Synchroniza
5e80: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 20  tion Type Flags 
5e90: 7b 48 31 30 32 36 30 7d 20 3c 48 31 31 31 32 30  {H10260} <H11120
5ea0: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  >.**.** When SQL
5eb0: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
5ec0: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
5ed0: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
5ee0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5ef0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
5f00: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
5f10: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
5f20: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
5f30: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
5f40: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
5f50: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
5f60: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
5f70: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
5f80: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
5f90: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
5fa0: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
5fb0: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
5fc0: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
5fd0: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
5fe0: 6c 75 73 68 65 64 2e 20 54 68 65 20 53 51 4c 49  lushed. The SQLI
5ff0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 66  TE_SYNC_NORMAL f
6000: 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  lag means.** to 
6010: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  use normal fsync
6020: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 20 54 68  () semantics. Th
6030: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
6040: 4c 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a  LL flag means.**
6050: 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 2d 58   to use Mac OS-X
6060: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20   style fullsync 
6070: 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63  instead of fsync
6080: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
6090: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
60a0: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32  L        0x00002
60b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
60c0: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20  SYNC_FULL       
60d0: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69     0x00003.#defi
60e0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  ne SQLITE_SYNC_D
60f0: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30  ATAONLY      0x0
6100: 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0010../*.** CAPI
6110: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
6120: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
6130: 64 6c 65 20 7b 48 31 31 31 31 30 7d 20 3c 53 32  dle {H11110} <S2
6140: 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  0110>.**.** An [
6150: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
6160: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
6170: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
6180: 74 68 65 20 4f 53 0a 2a 2a 20 69 6e 74 65 72 66  the OS.** interf
6190: 61 63 65 20 6c 61 79 65 72 2e 20 20 49 6e 64 69  ace layer.  Indi
61a0: 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66  vidual OS interf
61b0: 61 63 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ace implementati
61c0: 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74  ons will.** want
61d0: 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69   to subclass thi
61e0: 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65  s object by appe
61f0: 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c  nding additional
6200: 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74   fields.** for t
6210: 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54  heir own use.  T
6220: 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72  he pMethods entr
6230: 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  y is a pointer t
6240: 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  o an.** [sqlite3
6250: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6260: 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
6270: 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72   methods for per
6280: 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f  forming.** I/O o
6290: 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65  perations on the
62a0: 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74   open file..*/.t
62b0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
62c0: 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74  lite3_file sqlit
62d0: 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20  e3_file;.struct 
62e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20  sqlite3_file {. 
62f0: 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
6300: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6310: 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20   *pMethods;  /* 
6320: 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f  Methods for an o
6330: 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a  pen file */.};..
6340: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6350: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c  OS Interface Fil
6360: 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64  e Virtual Method
6370: 73 20 4f 62 6a 65 63 74 20 7b 48 31 31 31 32 30  s Object {H11120
6380: 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a  } <S20110>.**.**
6390: 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e   Every file open
63a0: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
63b0: 65 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65  e3_vfs] xOpen me
63c0: 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61  thod populates a
63d0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  n.** [sqlite3_fi
63e0: 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20  le] object (or, 
63f0: 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61  more commonly, a
6400: 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
6410: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
6420: 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20  e] object) with 
6430: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
6440: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
6450: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73   object..** This
6460: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
6470: 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64  the methods used
6480: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
6490: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ous operations.*
64a0: 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70  * against the op
64b0: 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e  en file represen
64c0: 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ted by the [sqli
64d0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
64e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
64f0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
6500: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
6510: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
6520: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
6530: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
6540: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
6550: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
6560: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
6570: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
6580: 73 20 61 20 4d 61 63 20 4f 53 2d 58 20 73 74 79  s a Mac OS-X sty
6590: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
65a0: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
65b0: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
65c0: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
65d0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
65e0: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
65f0: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
6600: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
6610: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
6620: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
6630: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
6640: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
6650: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
6660: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
6670: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
6680: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
6690: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
66a0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
66b0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
66c0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
66d0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
66e0: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
66f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
6700: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
6710: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
6720: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
6730: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
6740: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
6750: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
6760: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
6770: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
6780: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
6790: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
67a0: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
67b0: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
67c0: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
67d0: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
67e0: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
67f0: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
6800: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
6810: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
6820: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
6830: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
6840: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
6850: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
6860: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
6870: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
6880: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
6890: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
68a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
68b0: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
68c0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
68d0: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
68e0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
68f0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
6900: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
6910: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
6920: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
6930: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
6940: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
6950: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
6960: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
6970: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
6980: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
6990: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
69a0: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
69b0: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
69c0: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
69d0: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
69e0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
69f0: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
6a00: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
6a10: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
6a20: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
6a30: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
6a40: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
6a50: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
6a60: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
6a70: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
6a80: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
6a90: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
6aa0: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
6ab0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
6ac0: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
6ad0: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
6ae0: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
6af0: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
6b00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
6b10: 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66  KSTATE | list of
6b20: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
6b30: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
6b40: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
6b50: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
6b60: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
6b70: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
6b80: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
6b90: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
6ba0: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
6bb0: 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20  onflicts..**.** 
6bc0: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
6bd0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
6be0: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
6bf0: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
6c00: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
6c10: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
6c20: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
6c30: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
6c40: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
6c50: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
6c60: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
6c70: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
6c80: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
6c90: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
6ca0: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
6cb0: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
6cc0: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
6cd0: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
6ce0: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
6cf0: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
6d00: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
6d10: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
6d20: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6d30: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
6d40: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6d50: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
6d60: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6d70: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
6d80: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6d90: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
6da0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6db0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
6dc0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6dd0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
6de0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6df0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
6e00: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
6e10: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6e20: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
6e30: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
6e40: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
6e50: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
6e60: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75  QUENTIAL].** </u
6e70: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
6e80: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6e90: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6ea0: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
6eb0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
6ec0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6ed0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6ee0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
6ef0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
6f00: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
6f10: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
6f20: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
6f30: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
6f40: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
6f50: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
6f60: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
6f70: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6f80: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6f90: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
6fa0: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
6fb0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
6fc0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
6fd0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
6fe0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
6ff0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
7000: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
7010: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
7020: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
7030: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
7040: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
7050: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
7060: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
7070: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
7080: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
7090: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
70a0: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
70b0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
70c0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
70d0: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f  hods sqlite3_io_
70e0: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
70f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7100: 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  ds {.  int iVers
7110: 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c  ion;.  int (*xCl
7120: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ose)(sqlite3_fil
7130: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65  e*);.  int (*xRe
7140: 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ad)(sqlite3_file
7150: 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  *, void*, int iA
7160: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
7170: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
7180: 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65  (*xWrite)(sqlite
7190: 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76  3_file*, const v
71a0: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
71b0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
71c0: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54  fst);.  int (*xT
71d0: 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33  runcate)(sqlite3
71e0: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
71f0: 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69  int64 size);.  i
7200: 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
7210: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66  te3_file*, int f
7220: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
7230: 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65  FileSize)(sqlite
7240: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
7250: 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a  _int64 *pSize);.
7260: 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73    int (*xLock)(s
7270: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7280: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c  t);.  int (*xUnl
7290: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
72a0: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
72b0: 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  (*xCheckReserved
72c0: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
72d0: 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  le*, int *pResOu
72e0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  t);.  int (*xFil
72f0: 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65  eControl)(sqlite
7300: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c  3_file*, int op,
7310: 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20   void *pArg);.  
7320: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a  int (*xSectorSiz
7330: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7340: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69  );.  int (*xDevi
7350: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
7360: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  s)(sqlite3_file*
7370: 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  );.  /* Addition
7380: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
7390: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
73a0: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
73b0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
73c0: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20  : Standard File 
73d0: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20  Control Opcodes 
73e0: 7b 48 31 31 33 31 30 7d 20 3c 53 33 30 38 30 30  {H11310} <S30800
73f0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  >.**.** These in
7400: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
7410: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
7420: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
7430: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
7440: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
7450: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
7460: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
7470: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7480: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
7490: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
74a0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
74b0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
74c0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
74d0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
74e0: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
74f0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7500: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
7510: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
7520: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
7530: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
7540: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
7550: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
7560: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
7570: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
7580: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
7590: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
75a0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
75b0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
75c0: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
75d0: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
75e0: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
75f0: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
7600: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e  g testing and on
7610: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  ly needs to be s
7620: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51  upported when SQ
7630: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20  LITE_TEST.** is 
7640: 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66  defined..*/.#def
7650: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
7660: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
7670: 20 20 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    1../*.** CAPI3
7680: 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c  REF: Mutex Handl
7690: 65 20 7b 48 31 37 31 31 30 7d 20 3c 53 32 30 31  e {H17110} <S201
76a0: 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75  30>.**.** The mu
76b0: 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69  tex module withi
76c0: 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73  n SQLite defines
76d0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
76e0: 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73   to be an.** abs
76f0: 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61  tract type for a
7700: 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20   mutex object.  
7710: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
7720: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61  never looks.** a
7730: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  t the internal r
7740: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66  epresentation of
7750: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74   an [sqlite3_mut
7760: 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a  ex].  It only.**
7770: 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e   deals with poin
7780: 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  ters to the [sql
7790: 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65  ite3_mutex] obje
77a0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65  ct..**.** Mutexe
77b0: 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73  s are created us
77c0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
77d0: 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  ex_alloc()]..*/.
77e0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
77f0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c  qlite3_mutex sql
7800: 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a  ite3_mutex;../*.
7810: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7820: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74  Interface Object
7830: 20 7b 48 31 31 31 34 30 7d 20 3c 53 32 30 31 30   {H11140} <S2010
7840: 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  0>.**.** An inst
7850: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
7860: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64  te3_vfs object d
7870: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
7880: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20  face between.** 
7890: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
78a0: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
78b0: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
78c0: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
78d0: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
78e0: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
78f0: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
7900: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a   file system"..*
7910: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
7920: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
7930: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
7940: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
7950: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
7960: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
7970: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
7980: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
7990: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
79a0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
79b0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
79c0: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
79d0: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
79e0: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
79f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
7a00: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
7a10: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
7a20: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
7a30: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
7a40: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
7a50: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
7a60: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
7a70: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
7a80: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
7a90: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
7aa0: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
7ab0: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
7ac0: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
7ad0: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
7ae0: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
7af0: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
7b00: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
7b10: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
7b20: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
7b30: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
7b40: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
7b50: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
7b60: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
7b70: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
7b80: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
7b90: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
7ba0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
7bb0: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
7bc0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
7bd0: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
7be0: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
7bf0: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
7c00: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
7c10: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
7c20: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
7c30: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
7c40: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
7c50: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
7c60: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
7c70: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
7c80: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
7c90: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
7ca0: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
7cb0: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
7cc0: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
7cd0: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
7ce0: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
7cf0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
7d00: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
7d10: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
7d20: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
7d30: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
7d40: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
7d50: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
7d60: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
7d70: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
7d80: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
7d90: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
7da0: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
7db0: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
7dc0: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
7dd0: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
7de0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
7df0: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
7e00: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
7e10: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
7e20: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
7e30: 2a 20 7b 48 31 31 31 34 31 7d 20 53 51 4c 69 74  * {H11141} SQLit
7e40: 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65  e will guarantee
7e50: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
7e60: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
7e70: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
7e80: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
7e90: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
7ea0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
7eb0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 20  ullPathname().  
7ec0: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67  SQLite further g
7ed0: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a  uarantees that.*
7ee0: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  * the string wil
7ef0: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
7f00: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
7f10: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
7f20: 6c 6c 65 64 2e 20 7b 45 4e 44 7d 20 20 42 65 63  lled. {END}  Bec
7f30: 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76  ause of the prev
7f40: 69 6f 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a 2a  ious sentense,.*
7f50: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  * the [sqlite3_f
7f60: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20  ile] can safely 
7f70: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20  store a pointer 
7f80: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  to the.** filena
7f90: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74  me if it needs t
7fa0: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66  o remember the f
7fb0: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65  ilename for some
7fc0: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74   reason..** If t
7fd0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
7fe0: 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20  ameter is xOpen 
7ff0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
8000: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20  r then xOpen.** 
8010: 6d 75 73 74 20 69 6e 76 69 74 65 20 69 74 73 20  must invite its 
8020: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61  own temporary na
8030: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e  me for the file.
8040: 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a    Whenever the .
8050: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
8060: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
8070: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
8080: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
8090: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
80a0: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
80b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
80c0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
80d0: 0a 2a 2a 20 7b 48 31 31 31 34 32 7d 20 54 68 65  .** {H11142} The
80e0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
80f0: 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75  to xOpen() inclu
8100: 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74  des all bits set
8110: 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73   in.** the flags
8120: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
8130: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
8140: 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65  .  Or if [sqlite
8150: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20  3_open()].** or 
8160: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
8170: 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  )] is used, then
8180: 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20   flags includes 
8190: 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c  at least.** [SQL
81a0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
81b0: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
81c0: 45 4e 5f 43 52 45 41 54 45 5d 2e 20 7b 45 4e 44  EN_CREATE]. {END
81d0: 7d 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20  }.** If xOpen() 
81e0: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
81f0: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
8200: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
8210: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
8220: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
8230: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
8240: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
8250: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
8260: 20 7b 48 31 31 31 34 33 7d 20 53 51 4c 69 74 65   {H11143} SQLite
8270: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
8280: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
8290: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
82a0: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
82b0: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
82c0: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
82d0: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
82e0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
82f0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
8300: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
8310: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
8320: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
8330: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
8340: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
8350: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
8360: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
8370: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
8380: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
8390: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
83a0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
83b0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
83c0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
83d0: 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45  NAL].** </ul> {E
83e0: 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ND}.**.** The fi
83f0: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
8400: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
8410: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
8420: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
8430: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
8440: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
8450: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
8460: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
8470: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
8480: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
8490: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
84a0: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
84b0: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
84c0: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
84d0: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
84e0: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
84f0: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
8500: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
8510: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
8520: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
8530: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
8540: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
8550: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
8560: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
8570: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
8580: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
8590: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
85a0: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
85b0: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
85c0: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
85d0: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
85e0: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
85f0: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
8600: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
8610: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
8620: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
8630: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
8640: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
8650: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
8660: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8670: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
8680: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
8690: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
86a0: 2a 20 7b 48 31 31 31 34 35 7d 20 54 68 65 20 5b  * {H11145} The [
86b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
86c0: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20  TEONCLOSE] flag 
86d0: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
86e0: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65  hould be.** dele
86f0: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  ted when it is c
8700: 6c 6f 73 65 64 2e 20 20 7b 48 31 31 31 34 36 7d  losed.  {H11146}
8710: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
8720: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
8730: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
8740: 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61 62 61  for TEMP  databa
8750: 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e  ses, journals an
8760: 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c  d for subjournal
8770: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 37  s..**.** {H11147
8780: 7d 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  } The [SQLITE_OP
8790: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c  EN_EXCLUSIVE] fl
87a0: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
87b0: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e  e should be open
87c0: 65 64 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  ed.** for exclus
87d0: 69 76 65 20 61 63 63 65 73 73 2e 20 20 54 68 69  ive access.  Thi
87e0: 73 20 66 6c 61 67 20 69 73 20 73 65 74 20 66 6f  s flag is set fo
87f0: 72 20 61 6c 6c 20 66 69 6c 65 73 20 65 78 63 65  r all files exce
8800: 70 74 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 61  pt.** for the ma
8810: 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
8820: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 38 7d  ..**.** {H11148}
8830: 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69   At least szOsFi
8840: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
8850: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
8860: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
8870: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
8880: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
8890: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
88a0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
88b0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 7b 45  ent to xOpen. {E
88c0: 4e 44 7d 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  ND}  The xOpen m
88d0: 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68  ethod does not h
88e0: 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61  ave to.** alloca
88f0: 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65  te the structure
8900: 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74  ; it should just
8910: 20 66 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 0a   fill it in..**.
8920: 2a 2a 20 7b 48 31 31 31 34 39 7d 20 54 68 65 20  ** {H11149} The 
8930: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
8940: 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20  o xAccess() may 
8950: 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  be [SQLITE_ACCES
8960: 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20  S_EXISTS].** to 
8970: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
8980: 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stence of a file
8990: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
89a0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74  ESS_READWRITE] t
89b0: 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65  o.** test whethe
89c0: 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64  r a file is read
89d0: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
89e0: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
89f0: 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f  CESS_READ].** to
8a00: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
8a10: 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74  file is at least
8a20: 20 72 65 61 64 61 62 6c 65 2e 20 7b 45 4e 44 7d   readable. {END}
8a30: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
8a40: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
8a50: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 35 30 7d  ..**.** {H11150}
8a60: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77   SQLite will alw
8a70: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
8a80: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
8a90: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
8aa0: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
8ab0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
8ac0: 20 7b 48 31 31 31 35 31 7d 20 54 68 65 20 65 78   {H11151} The ex
8ad0: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
8ae0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
8af0: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
8b00: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
8b10: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
8b20: 20 7b 45 4e 44 7d 20 20 49 66 20 74 68 65 20 6f   {END}  If the o
8b30: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
8b40: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
8b50: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
8b60: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
8b70: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
8b80: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
8b90: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
8ba0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
8bb0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
8bc0: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
8bd0: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
8be0: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
8bf0: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
8c00: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
8c10: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
8c20: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
8c30: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61  s(), xSleep(), a
8c40: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  nd xCurrentTime(
8c50: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
8c60: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
8c70: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
8c80: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
8c90: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
8ca0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
8cb0: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
8cc0: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
8cd0: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
8ce0: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
8cf0: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
8d00: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
8d10: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
8d20: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
8d30: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
8d40: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
8d50: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
8d60: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
8d70: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
8d80: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
8d90: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
8da0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
8db0: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
8dc0: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
8dd0: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
8de0: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43  s given.  The xC
8df0: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
8e00: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
8e10: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
8e20: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
8e30: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
8e40: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
8e50: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
8e60: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72  sqlite3_vfs;.str
8e70: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
8e80: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
8e90: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
8ea0: 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f  Structure versio
8eb0: 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e  n number */.  in
8ec0: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
8ed0: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
8ee0: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
8ef0: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
8f00: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
8f10: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
8f20: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
8f30: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
8f40: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
8f50: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
8f60: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
8f70: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
8f80: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
8f90: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
8fa0: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
8fb0: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
8fc0: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
8fd0: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
8fe0: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
8ff0: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
9000: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
9010: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
9020: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
9030: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
9040: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
9050: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
9060: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
9070: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
9080: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
9090: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
90a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
90b0: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
90c0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
90d0: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
90e0: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
90f0: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
9100: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
9110: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
9120: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
9130: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
9140: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
9150: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
9160: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
9170: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
9180: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
9190: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
91a0: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
91b0: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53  ;.  void *(*xDlS
91c0: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
91d0: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
91e0: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20  ar *zSymbol);.  
91f0: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
9200: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
9210: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
9220: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
9230: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
9240: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
9250: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
9260: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9270: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
9280: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
9290: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
92a0: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
92b0: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
92c0: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
92d0: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
92e0: 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65  *);.  /* New fie
92f0: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
9300: 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65  ded in figure ve
9310: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
9320: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
9330: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
9340: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
9350: 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ppens. */.};../*
9360: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
9370: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
9380: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 20 7b  ess VFS method {
9390: 48 31 31 31 39 30 7d 20 3c 48 31 31 31 34 30 3e  H11190} <H11140>
93a0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 39 31 7d 20  .**.** {H11191} 
93b0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
93c0: 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75  nstants can be u
93d0: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
93e0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
93f0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
9400: 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  hod of an [sqlit
9410: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
9420: 7b 45 4e 44 7d 20 20 54 68 65 79 20 64 65 74 65  {END}  They dete
9430: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
9440: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
9450: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
9460: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
9470: 66 6f 72 2e 0a 2a 2a 20 7b 48 31 31 31 39 32 7d  for..** {H11192}
9480: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
9490: 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20  ESS_EXISTS, the 
94a0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
94b0: 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20  * simply checks 
94c0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
94d0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 7b 48 31 31   exists..** {H11
94e0: 31 39 33 7d 20 57 69 74 68 20 53 51 4c 49 54 45  193} With SQLITE
94f0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
9500: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
9510: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
9520: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
9530: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
9540: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a  e and writable..
9550: 2a 2a 20 7b 48 31 31 31 39 34 7d 20 57 69 74 68  ** {H11194} With
9560: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
9570: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
9580: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
9590: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
95a0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a  le is readable..
95b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
95c0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
95d0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
95e0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
95f0: 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53  RITE 1.#define S
9600: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
9610: 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20  D      2../*.** 
9620: 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61  CAPI3REF: Initia
9630: 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20  lize The SQLite 
9640: 4c 69 62 72 61 72 79 20 7b 48 31 30 31 33 30 7d  Library {H10130}
9650: 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 31 30 30   <S20000><S30100
9660: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
9670: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9680: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
9690: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
96a0: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
96b0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
96c0: 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64  n() routine.** d
96d0: 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72  eallocates any r
96e0: 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65  esources that we
96f0: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
9700: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9710: 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ze()..**.** A ca
9720: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
9730: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e  itialize() is an
9740: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
9750: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68  l if it is.** th
9760: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
9770: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9780: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72  ) is invoked dur
9790: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
97a0: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65   of.** the proce
97b0: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20  ss, or if it is 
97c0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
97d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
97e0: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
97f0: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  * following a ca
9800: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
9810: 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 20  utdown().  Only 
9820: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
9830: 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  l.** of sqlite3_
9840: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65  initialize() doe
9850: 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61  s any initializa
9860: 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72  tion.  All other
9870: 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61   calls.** are ha
9880: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a  rmless no-ops..*
9890: 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72  *.** Among other
98a0: 20 74 68 69 6e 67 73 2c 20 73 71 6c 69 74 65 33   things, sqlite3
98b0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 68  _initialize() sh
98c0: 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  all invoke.** sq
98d0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
98e0: 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 73 71 6c    Similarly, sql
98f0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
9900: 2a 2a 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 20  ** shall invoke 
9910: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
9920: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
9930: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9940: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
9950: 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20 73 75   SQLITE_OK on su
9960: 63 63 65 73 73 2e 0a 2a 2a 20 49 66 20 66 6f 72  ccess..** If for
9970: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
9980: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9990: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
99a0: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
99b0: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
99c0: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
99d0: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
99e0: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
99f0: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
9a00: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
9a10: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
9a20: 65 72 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4f  er than SQLITE_O
9a30: 4b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  K..**.** The sql
9a40: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9a50: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
9a60: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
9a70: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
9a80: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
9a90: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
9aa0: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
9ab0: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
9ac0: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
9ad0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9ae0: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
9af0: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
9b00: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
9b10: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
9b20: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
9b30: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
9b40: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
9b50: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
9b60: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
9b70: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
9b80: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
9b90: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
9ba0: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 48 6f 77  ** already.  How
9bb0: 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20  ever, if SQLite 
9bc0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
9bd0: 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
9be0: 5f 41 55 54 4f 49 4e 49 54 0a 2a 2a 20 63 6f 6d  _AUTOINIT.** com
9bf0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
9c00: 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d  , then the autom
9c10: 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71  atic calls to sq
9c20: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9c30: 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65  ().** are omitte
9c40: 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  d and the applic
9c50: 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20  ation must call 
9c60: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9c70: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a  ze() directly.**
9c80: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
9c90: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
9ca0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72   interface.  For
9cb0: 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69   maximum portabi
9cc0: 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72  lity,.** it is r
9cd0: 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
9ce0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77  applications alw
9cf0: 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ays invoke sqlit
9d00: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
9d10: 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f  ** directly prio
9d20: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
9d30: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
9d40: 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72  rface.  Future r
9d50: 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51  eleases.** of SQ
9d60: 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65  Lite may require
9d70: 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72   this.  In other
9d80: 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61   words, the beha
9d90: 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a  vior exhibited.*
9da0: 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
9db0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 53   compiled with S
9dc0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
9dd0: 4e 49 54 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  NIT might become
9de0: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
9df0: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
9e00: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
9e10: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
9e20: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
9e30: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
9e40: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
9e50: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
9e60: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
9e70: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
9e80: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
9e90: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
9ea0: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
9eb0: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
9ec0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
9ed0: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
9ee0: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
9ef0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
9f00: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
9f10: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
9f20: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
9f30: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
9f40: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
9f50: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
9f60: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
9f70: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
9f80: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
9f90: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
9fa0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
9fb0: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
9fc0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
9fd0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
9fe0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
9ff0: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
a000: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a010: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
a020: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
a030: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
a040: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
a050: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
a060: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
a070: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
a080: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
a090: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
a0a0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
a0b0: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
a0c0: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
a0d0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
a0e0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a0f0: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
a100: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
a110: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
a120: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
a130: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
a140: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
a150: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
a160: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
a170: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
a180: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 75  s compiled for u
a190: 6e 69 78 2c 20 77 69 6e 64 6f 77 73 2c 20 6f 72  nix, windows, or
a1a0: 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 62   os/2..** When b
a1b0: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
a1c0: 6c 61 74 66 6f 72 6d 73 20 28 75 73 69 6e 67 20  latforms (using 
a1d0: 74 68 65 20 53 51 4c 49 54 45 5f 4f 53 5f 4f 54  the SQLITE_OS_OT
a1e0: 48 45 52 3d 31 20 63 6f 6d 70 69 6c 65 2d 74 69  HER=1 compile-ti
a1f0: 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
a200: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
a210: 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
a220: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
a230: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
a240: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
a250: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a260: 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
a270: 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
a280: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
a290: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
a2a0: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
a2b0: 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
a2c0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
a2d0: 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
a2e0: 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
a2f0: 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
a300: 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73  ailure..*/.int s
a310: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a320: 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  e(void);.int sql
a330: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f  ite3_shutdown(vo
a340: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
a350: 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
a360: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  int sqlite3_os_e
a370: 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
a380: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
a390: 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
a3a0: 65 20 4c 69 62 72 61 72 79 20 7b 48 31 30 31 34  e Library {H1014
a3b0: 35 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 32  5} <S20000><S302
a3c0: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
a3d0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
a3e0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
a3f0: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
a400: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
a410: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
a420: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
a430: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
a440: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
a450: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
a460: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
a470: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
a480: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
a490: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
a4a0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
a4b0: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
a4c0: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
a4d0: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
a4e0: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
a4f0: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
a500: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
a510: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
a520: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
a530: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
a540: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
a550: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
a560: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
a570: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
a580: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
a590: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
a5a0: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
a5b0: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
a5c0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
a5d0: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
a5e0: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
a5f0: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
a600: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
a610: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
a620: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
a630: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
a640: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
a650: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
a660: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
a670: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 4e 6f 74 65  down()]..** Note
a680: 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
a690: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a6a0: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
a6b0: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
a6c0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
a6d0: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
a6e0: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
a6f0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
a700: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
a710: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
a720: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
a730: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  n integer.** [SQ
a740: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
a750: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69  LETHREAD | confi
a760: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
a770: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
a780: 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
a790: 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
a7a0: 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
a7b0: 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
a7c0: 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
a7d0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
a7e0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
a7f0: 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f  INGLETHREAD | co
a800: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
a810: 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
a820: 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
a830: 0a 2a 2a 20 57 68 65 6e 20 61 20 63 6f 6e 66 69  .** When a confi
a840: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
a850: 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
a860: 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
a870: 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49   SQLITE_OK..** I
a880: 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
a890: 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
a8a0: 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
a8b0: 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
a8c0: 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
a8d0: 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
a8e0: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
a8f0: 65 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  e]..**.** The sq
a900: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
a910: 6e 74 65 72 66 61 63 65 20 69 73 20 63 6f 6e 73  nterface is cons
a920: 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
a930: 74 61 6c 20 69 6e 20 74 68 61 74 0a 2a 2a 20 6e  tal in that.** n
a940: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
a950: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
a960: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
a970: 72 65 6c 65 61 73 65 73 20 61 6e 64 20 65 78 69  releases and exi
a980: 73 74 69 6e 67 0a 2a 2a 20 63 6f 6e 66 69 67 75  sting.** configu
a990: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
a9a0: 61 79 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ay be discontinu
a9b0: 65 64 20 6f 72 20 6d 6f 64 69 66 69 65 64 2e 0a  ed or modified..
a9c0: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
a9d0: 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
a9e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
a9f0: 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
aa00: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
aa10: 20 20 7b 48 31 30 31 38 30 7d 20 3c 53 32 30 30    {H10180} <S200
aa20: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
aa30: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
aa40: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
aa50: 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66  sed to make conf
aa60: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
aa70: 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62  nges to a [datab
aa80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
aa90: 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
aaa0: 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a  is similar to.**
aab0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
aac0: 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  ()] except that 
aad0: 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c  the changes appl
aae0: 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  y to a single.**
aaf0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
ab00: 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65  ction] (specifie
ab10: 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
ab20: 72 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a  rgument).  The.*
ab30: 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  * sqlite3_db_con
ab40: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
ab50: 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
ab60: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74   immediately aft
ab70: 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  er.** the databa
ab80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
ab90: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
aba0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
abb0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
abc0: 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  n16()], or [sqli
abd0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
abe0: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f   .**.** The seco
abf0: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
ac00: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
ac10: 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
ac20: 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
ac30: 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69 6e 74  on verb - an int
ac40: 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 69  eger code that i
ac50: 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a 2a 2a  ndicates what.**
ac60: 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
ac70: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
ac80: 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
ac90: 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 43 68 6f  nfigured..** Cho
aca0: 69 63 65 73 20 66 6f 72 20 74 68 69 73 20 76 61  ices for this va
acb0: 6c 75 65 20 61 72 65 20 5b 53 51 4c 49 54 45 5f  lue are [SQLITE_
acc0: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
acd0: 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73 20  ]..** New verbs 
ace0: 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62 65  are likely to be
acf0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
ad00: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
ad10: 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ite..*/.int sqli
ad20: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
ad30: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
ad40: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
ad50: 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
ad60: 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
ad70: 73 20 7b 48 31 30 31 35 35 7d 20 3c 53 32 30 31  s {H10155} <S201
ad80: 32 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  20>.**.** An ins
ad90: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
ada0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
adb0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
adc0: 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
add0: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
ade0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
adf0: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
ae00: 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
ae10: 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
ae20: 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
ae30: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
ae40: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
ae50: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
ae60: 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
ae70: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
ae80: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
ae90: 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
aea0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
aeb0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
aec0: 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 42 79 20  IG_MALLOC].  By 
aed0: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
aee0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
aef0: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
af00: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
af10: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 64 75 72 69  3_config()] duri
af20: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
af30: 2c 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74  , an.** applicat
af40: 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20  ion can specify 
af50: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  an alternative m
af60: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
af70: 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 66 6f   subsystem.** fo
af80: 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20  r SQLite to use 
af90: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
afa0: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
afb0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
afc0: 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
afd0: 73 20 77 69 74 68 20 61 20 62 75 69 6c 74 2d 69  s with a built-i
afe0: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
aff0: 6f 72 20 74 68 61 74 20 69 73 0a 2a 2a 20 70 65  or that is.** pe
b000: 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
b010: 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
b020: 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
b030: 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
b040: 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
b050: 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
b060: 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
b070: 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
b080: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
b090: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
b0a0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
b0b0: 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
b0c0: 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
b0d0: 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
b0e0: 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
b0f0: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
b100: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
b110: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
b120: 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
b130: 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
b140: 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
b150: 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
b160: 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
b170: 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
b180: 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
b190: 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
b1a0: 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
b1b0: 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 46 72 65 65  e xMalloc, xFree
b1c0: 2c 20 61 6e 64 20 78 52 65 61 6c 6c 6f 63 20 6d  , and xRealloc m
b1d0: 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
b1e0: 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
b1f0: 6c 6f 63 28 29 2c 20 66 72 65 65 28 29 2c 20 61  loc(), free(), a
b200: 6e 64 20 72 65 61 6c 6c 6f 63 28 29 20 66 75 6e  nd realloc() fun
b210: 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20  ctions from the 
b220: 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79  standard library
b230: 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
b240: 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
b250: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
b260: 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
b270: 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
b280: 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
b290: 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
b2a0: 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
b2b0: 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
b2c0: 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
b2d0: 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
b2e0: 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
b2f0: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
b300: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
b310: 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
b320: 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
b330: 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
b340: 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
b350: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
b360: 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
b370: 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
b380: 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
b390: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
b3a0: 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
b3b0: 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
b3c0: 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
b3d0: 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
b3e0: 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
b3f0: 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
b400: 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
b410: 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
b420: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
b430: 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
b440: 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
b450: 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72  allocator.  (For
b460: 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
b470: 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
b480: 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
b490: 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
b4a0: 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
b4b0: 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
b4c0: 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
b4d0: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
b4e0: 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
b4f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
b500: 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
b510: 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
b520: 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
b530: 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
b540: 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
b550: 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
b560: 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
b570: 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
b580: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
b590: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
b5a0: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
b5b0: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65  thods sqlite3_me
b5c0: 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  m_methods;.struc
b5d0: 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  t sqlite3_mem_me
b5e0: 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a  thods {.  void *
b5f0: 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b  (*xMalloc)(int);
b600: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f           /* Memo
b610: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75  ry allocation fu
b620: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  nction */.  void
b630: 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29   (*xFree)(void*)
b640: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72  ;          /* Fr
b650: 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63  ee a prior alloc
b660: 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ation */.  void 
b670: 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69  *(*xRealloc)(voi
b680: 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73  d*,int);  /* Res
b690: 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f  ize an allocatio
b6a0: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69  n */.  int (*xSi
b6b0: 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ze)(void*);     
b6c0: 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20        /* Return 
b6d0: 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61  the size of an a
b6e0: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
b6f0: 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69  nt (*xRoundup)(i
b700: 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  nt);          /*
b710: 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73   Round up reques
b720: 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61  t size to alloca
b730: 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69  tion size */.  i
b740: 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64  nt (*xInit)(void
b750: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
b760: 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   Initialize the 
b770: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
b780: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68   */.  void (*xSh
b790: 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20  utdown)(void*); 
b7a0: 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61       /* Deinitia
b7b0: 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
b7c0: 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
b7d0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
b7e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
b7f0: 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e   Argument to xIn
b800: 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f  it() and xShutdo
b810: 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  wn() */.};../*.*
b820: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
b830: 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
b840: 73 20 7b 48 31 30 31 36 30 7d 20 3c 53 32 30 30  s {H10160} <S200
b850: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
b860: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
b870: 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
b880: 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
b890: 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
b8a0: 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
b8b0: 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
b8c0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
b8d0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
b8e0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
b8f0: 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
b900: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
b910: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
b920: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
b930: 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
b940: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
b950: 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
b960: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
b970: 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
b980: 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
b990: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
b9a0: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  m [sqlite3_confi
b9b0: 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
b9c0: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
b9d0: 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20  ll worked.  The 
b9e0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
b9f0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
ba00: 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
ba10: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
ba20: 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
ba30: 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
ba40: 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
ba50: 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
ba60: 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
ba70: 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
ba80: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
ba90: 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
baa0: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
bab0: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
bac0: 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f   option.  This o
bad0: 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a  ption disables.*
bae0: 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61  * all mutexing a
baf0: 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69  nd puts SQLite i
bb00: 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65  nto a mode where
bb10: 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20   it can only be 
bb20: 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e  used.** by a sin
bb30: 67 6c 65 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e  gle thread.</dd>
bb40: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
bb50: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
bb60: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
bb70: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
bb80: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
bb90: 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70  option.  This op
bba0: 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a  tion disables.**
bbb0: 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
bbc0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
bbd0: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
bbe0: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
bbf0: 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
bc00: 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
bc10: 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
bc20: 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
bc30: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
bc40: 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
bc50: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
bc60: 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
bc70: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
bc80: 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
bc90: 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
bca0: 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
bcb0: 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
bcc0: 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2e 3c 2f  * environment.</
bcd0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
bce0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
bcf0: 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
bd00: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
bd10: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
bd20: 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73 20  s option.  This 
bd30: 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
bd40: 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
bd50: 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
bd60: 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
bd70: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
bd80: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
bd90: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
bda0: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
bdb0: 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
bdc0: 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
bdd0: 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
bde0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
bdf0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
be00: 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
be10: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
be20: 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
be30: 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
be40: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
be50: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
be60: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
be70: 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
be80: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
be90: 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
bea0: 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
beb0: 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
bec0: 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
bed0: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
bee0: 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
bef0: 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
bf00: 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 54 68 69  me..**.** <p>Thi
bf10: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
bf20: 6f 70 74 69 6f 6e 20 6d 65 72 65 6c 79 20 73 65  option merely se
bf30: 74 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ts the default m
bf40: 75 74 65 78 20 0a 2a 2a 20 62 65 68 61 76 69 6f  utex .** behavio
bf50: 72 20 74 6f 20 73 65 72 69 61 6c 69 7a 65 20 61  r to serialize a
bf60: 63 63 65 73 73 20 74 6f 20 5b 64 61 74 61 62 61  ccess to [databa
bf70: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e  se connections].
bf80: 20 20 49 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20    Individual.** 
bf90: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
bfa0: 74 69 6f 6e 73 5d 20 63 61 6e 20 6f 76 65 72 72  tions] can overr
bfb0: 69 64 65 20 74 68 69 73 20 73 65 74 74 69 6e 67  ide this setting
bfc0: 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 53  .** using the [S
bfd0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
bfe0: 45 58 5d 20 66 6c 61 67 20 74 6f 20 5b 73 71 6c  EX] flag to [sql
bff0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
c000: 3c 2f 70 3e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  </p></dd>.**.** 
c010: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
c020: 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
c030: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
c040: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
c050: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
c060: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
c070: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
c080: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
c090: 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
c0a0: 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
c0b0: 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
c0c0: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
c0d0: 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
c0e0: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
c0f0: 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
c100: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
c110: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c120: 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
c130: 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64   into SQLite.</d
c140: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
c150: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
c160: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
c170: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
c180: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
c190: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
c1a0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
c1b0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
c1c0: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
c1d0: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
c1e0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
c1f0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
c200: 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
c210: 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
c220: 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
c230: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
c240: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68   routines..** Th
c250: 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
c260: 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
c270: 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65  d the default me
c280: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
c290: 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
c2a0: 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20   a wrapper that 
c2b0: 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f  simulations memo
c2c0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
c2d0: 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63  ilure or.** trac
c2e0: 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c  ks memory usage,
c2f0: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64   for example.</d
c300: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
c310: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
c320: 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
c330: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
c340: 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
c350: 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20  nt of type int, 
c360: 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
c370: 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68   .** boolean, wh
c380: 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ich enables or d
c390: 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c  isables the coll
c3a0: 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79  ection of memory
c3b0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20   allocation .** 
c3c0: 73 74 61 74 69 73 74 69 63 73 2e 20 57 68 65 6e  statistics. When
c3d0: 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66   disabled, the f
c3e0: 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20  ollowing SQLite 
c3f0: 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d  interfaces becom
c400: 65 20 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65 72 61 74  e .** non-operat
c410: 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e  ional:.**   <ul>
c420: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
c430: 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
c440: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
c450: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
c460: 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c  hwater()].**   <
c470: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  li> [sqlite3_sof
c480: 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a  t_heap_limit()].
c490: 2a 2a 20 20 20 3c 6c 69 3e 20 73 71 6c 69 74 65  **   <li> sqlite
c4a0: 33 5f 6d 65 6d 6f 72 79 5f 73 74 61 74 75 73 28  3_memory_status(
c4b0: 29 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 0a 2a 2a 20  ).**   </ul>.** 
c4c0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
c4d0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
c4e0: 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
c4f0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70  d>This option sp
c500: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
c510: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
c520: 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
c530: 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63  se for.** scratc
c540: 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65  h memory.  There
c550: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
c560: 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72  ents:  A pointer
c570: 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20   to the memory, 
c580: 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
c590: 61 63 68 20 73 63 72 61 74 63 68 20 62 75 66 66  ach scratch buff
c5a0: 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65  er (sz), and the
c5b0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 75 66 66 65   number of buffe
c5c0: 72 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a  rs (N).  The sz.
c5d0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
c5e0: 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f   be a multiple o
c5f0: 66 20 31 36 2e 20 54 68 65 20 66 69 72 73 74 0a  f 16. The first.
c600: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
c610: 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
c620: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
c630: 6c 65 61 73 74 20 28 73 7a 2b 34 29 2a 4e 20 62  least (sz+4)*N b
c640: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
c650: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  ** SQLite will u
c660: 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20  se no more than 
c670: 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66  one scratch buff
c680: 65 72 20 61 74 20 6f 6e 63 65 20 70 65 72 20 74  er at once per t
c690: 68 72 65 61 64 2c 20 73 6f 0a 2a 2a 20 4e 20 73  hread, so.** N s
c6a0: 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20  hould be set to 
c6b0: 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78  the expected max
c6c0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
c6d0: 68 72 65 61 64 73 2e 20 20 54 68 65 20 73 7a 0a  hreads.  The sz.
c6e0: 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f  ** parameter sho
c6f0: 75 6c 64 20 62 65 20 36 20 74 69 6d 65 73 20 74  uld be 6 times t
c700: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
c710: 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
c720: 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 53 63  page size..** Sc
c730: 72 61 74 63 68 20 62 75 66 66 65 72 73 20 61 72  ratch buffers ar
c740: 65 20 75 73 65 64 20 61 73 20 70 61 72 74 20 6f  e used as part o
c750: 66 20 74 68 65 20 62 74 72 65 65 20 62 61 6c 61  f the btree bala
c760: 6e 63 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  nce operation.  
c770: 49 66 0a 2a 2a 20 54 68 65 20 62 74 72 65 65 20  If.** The btree 
c780: 62 61 6c 61 6e 63 65 72 20 6e 65 65 64 73 20 61  balancer needs a
c790: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79  dditional memory
c7a0: 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
c7b0: 70 72 6f 76 69 64 65 64 20 62 79 0a 2a 2a 20 73  provided by.** s
c7c0: 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 6f  cratch buffers o
c7d0: 72 20 69 66 20 6e 6f 20 73 63 72 61 74 63 68 20  r if no scratch 
c7e0: 62 75 66 66 65 72 20 73 70 61 63 65 20 69 73 20  buffer space is 
c7f0: 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
c800: 53 51 4c 69 74 65 0a 2a 2a 20 67 6f 65 73 20 74  SQLite.** goes t
c810: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
c820: 63 28 29 5d 20 74 6f 20 6f 62 74 61 69 6e 20 74  c()] to obtain t
c830: 68 65 20 6d 65 6d 6f 72 79 20 69 74 20 6e 65 65  he memory it nee
c840: 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ds.</dd>.**.** <
c850: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
c860: 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a  _PAGECACHE</dt>.
c870: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
c880: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
c890: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
c8a0: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
c8b0: 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74  can use for.** t
c8c0: 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
c8d0: 20 63 61 63 68 65 2e 20 20 54 68 65 72 65 20 61   cache.  There a
c8e0: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
c8f0: 74 73 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  ts: A pointer to
c900: 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20   the.** memory, 
c910: 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
c920: 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a   page buffer (sz
c930: 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
c940: 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a  r of pages (N)..
c950: 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
c960: 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 77  nt must be a pow
c970: 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
c980: 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 2e  n 512 and 32768.
c990: 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
c9a0: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
c9b0: 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63  oint to an alloc
c9c0: 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73  ation of at leas
c9d0: 74 20 28 73 7a 2b 34 29 2a 4e 20 62 79 74 65 73  t (sz+4)*N bytes
c9e0: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53   of memory..** S
c9f0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
ca00: 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
ca10: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
ca20: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69  argument to sati
ca30: 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72  sfy its.** memor
ca40: 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20  y needs for the 
ca50: 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68  first N pages th
ca60: 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61  at it adds to ca
ca70: 63 68 65 2e 20 20 49 66 20 61 64 64 69 74 69 6f  che.  If additio
ca80: 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
ca90: 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
caa0: 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
cab0: 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
cac0: 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a  is option, then.
cad0: 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  ** SQLite goes t
cae0: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
caf0: 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64  c()] for the add
cb00: 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20  itional storage 
cb10: 73 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  space.</dd>.**.*
cb20: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
cb30: 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
cb40: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
cb50: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
cb60: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
cb70: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  r that SQLite wi
cb80: 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c  ll use.** for al
cb90: 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
cba0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
cbb0: 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20  on needs beyond 
cbc0: 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a  those provided.*
cbd0: 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  * for by [SQLITE
cbe0: 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
cbf0: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
cc00: 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
cc10: 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
cc20: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20  ee arguments: A 
cc30: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
cc40: 65 6d 6f 72 79 2c 20 74 68 65 20 6e 75 6d 62 65  emory, the numbe
cc50: 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
cc60: 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
cc70: 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
cc80: 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
cc90: 69 7a 65 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20  ize.  If.** the 
cca0: 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
ccb0: 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
ccc0: 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
ccd0: 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
cce0: 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
ccf0: 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
cd00: 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
cd10: 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
cd20: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
cd30: 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
cd40: 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
cd50: 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
cd60: 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68  _MALLOC].  If th
cd70: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
cd80: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
cd90: 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49  and either [SQLI
cda0: 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
cdb0: 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  3] or.** [SQLITE
cdc0: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
cdd0: 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
cde0: 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
cdf0: 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
ce00: 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
ce10: 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
ce20: 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
ce30: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
ce40: 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ds.</dd>.**.** <
ce50: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
ce60: 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  _MUTEX</dt>.** <
ce70: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
ce80: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
ce90: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
cea0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
ceb0: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
cec0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
ced0: 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
cee0: 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
cef0: 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
cf00: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
cf10: 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
cf20: 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
cf30: 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65   in place.** the
cf40: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
cf50: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
cf60: 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  e.</dd>.**.** <d
cf70: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
cf80: 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  GETMUTEX</dt>.**
cf90: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
cfa0: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
cfb0: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
cfc0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
cfd0: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
cfe0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
cff0: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
d000: 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
d010: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
d020: 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
d030: 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
d040: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
d050: 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
d060: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69  routines..** Thi
d070: 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
d080: 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
d090: 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
d0a0: 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
d0b0: 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
d0c0: 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
d0d0: 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
d0e0: 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
d0f0: 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
d100: 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
d110: 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a  example.</dd>.**
d120: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
d130: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
d140: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
d150: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
d160: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
d170: 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
d180: 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79  efault.** memory
d190: 20 61 6c 6c 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61   allcation looka
d1a0: 73 69 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  side optimizatio
d1b0: 6e 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  n.  The first ar
d1c0: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
d1d0: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
d1e0: 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
d1f0: 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
d200: 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
d210: 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
d220: 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
d230: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d240: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
d250: 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
d260: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
d270: 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
d280: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
d290: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
d2a0: 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
d2b0: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
d2c0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d2d0: 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
d2e0: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
d2f0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
d300: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
d310: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
d320: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
d330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
d340: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
d350: 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
d360: 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
d370: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
d380: 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
d390: 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
d3a0: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
d3b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d3c0: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
d3d0: 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
d3e0: 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
d3f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d400: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
d410: 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
d420: 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
d430: 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
d440: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d450: 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
d460: 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
d470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
d480: 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
d490: 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
d4a0: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
d4b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d4c0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
d4d0: 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
d4e0: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
d4f0: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
d500: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
d510: 4e 4b 41 4c 4c 4f 43 20 20 20 31 32 20 20 2f 2a  NKALLOC   12  /*
d520: 20 69 6e 74 20 74 68 72 65 73 68 6f 6c 64 20 2a   int threshold *
d530: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d540: 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
d550: 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
d560: 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  int */.../*.** C
d570: 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
d580: 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
d590: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
d5a0: 20 7b 48 31 32 32 30 30 7d 20 3c 53 31 30 37 30   {H12200} <S1070
d5b0: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
d5c0: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
d5d0: 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
d5e0: 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
d5f0: 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
d600: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
d610: 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
d620: 6f 66 20 53 51 4c 69 74 65 2e 20 54 68 65 20 65  of SQLite. The e
d630: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
d640: 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  * codes are disa
d650: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
d660: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
d670: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 63 6f 6e  ompatibility con
d680: 73 69 64 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a  siderations..**.
d690: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
d6a0: 2a 0a 2a 2a 20 7b 48 31 32 32 30 31 7d 20 45 61  *.** {H12201} Ea
d6b0: 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65  ch new [database
d6c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 68 61   connection] sha
d6d0: 6c 6c 20 68 61 76 65 20 74 68 65 0a 2a 2a 20 20  ll have the.**  
d6e0: 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65          [extende
d6f0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
d700: 66 65 61 74 75 72 65 20 64 69 73 61 62 6c 65 64  feature disabled
d710: 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
d720: 2a 2a 20 7b 48 31 32 32 30 32 7d 20 54 68 65 20  ** {H12202} The 
d730: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
d740: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 44  d_result_codes(D
d750: 2c 46 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73  ,F)] interface s
d760: 68 61 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20  hall enable.**  
d770: 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65          [extende
d780: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
d790: 66 6f 72 20 74 68 65 20 20 5b 64 61 74 61 62 61  for the  [databa
d7a0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
d7b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66 20  .**          if 
d7c0: 74 68 65 20 46 20 70 61 72 61 6d 65 74 65 72 20  the F parameter 
d7d0: 69 73 20 74 72 75 65 2c 20 6f 72 20 64 69 73 61  is true, or disa
d7e0: 62 6c 65 20 74 68 65 6d 20 69 66 20 46 20 69 73  ble them if F is
d7f0: 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73   false..*/.int s
d800: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
d810: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
d820: 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
d830: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
d840: 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
d850: 52 6f 77 69 64 20 7b 48 31 32 32 32 30 7d 20 3c  Rowid {H12220} <
d860: 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 61  S10700>.**.** Ea
d870: 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53  ch entry in an S
d880: 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20  QLite table has 
d890: 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20  a unique 64-bit 
d8a0: 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65  signed.** intege
d8b0: 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65  r key called the
d8c0: 20 22 72 6f 77 69 64 22 2e 20 54 68 65 20 72 6f   "rowid". The ro
d8d0: 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
d8e0: 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
d8f0: 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
d900: 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
d910: 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
d920: 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
d930: 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
d940: 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
d950: 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
d960: 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a  ed columns. If.*
d970: 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
d980: 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
d990: 20 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59   INTEGER PRIMARY
d9a0: 20 4b 45 59 20 74 68 65 6e 20 74 68 61 74 20 63   KEY then that c
d9b0: 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74  olumn.** is anot
d9c0: 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68  her alias for th
d9d0: 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54  e rowid..**.** T
d9e0: 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
d9f0: 72 6e 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66  rns the rowid of
da00: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
da10: 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 49  .** successful I
da20: 4e 53 45 52 54 20 69 6e 74 6f 20 74 68 65 20 64  NSERT into the d
da30: 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65  atabase from the
da40: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
da50: 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ction].** in the
da60: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
da70: 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66    If no successf
da80: 75 6c 20 49 4e 53 45 52 54 73 0a 2a 2a 20 68 61  ul INSERTs.** ha
da90: 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
daa0: 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73   on that databas
dab0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65  e connection, ze
dac0: 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
dad0: 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53 45  **.** If an INSE
dae0: 52 54 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  RT occurs within
daf0: 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e   a trigger, then
db00: 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68   the rowid of th
db10: 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
db20: 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  w is returned by
db30: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73   this routine as
db40: 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
db50: 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gger is running.
db60: 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
db70: 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61   trigger termina
db80: 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  tes, the value r
db90: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
dba0: 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72  routine.** rever
dbb0: 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76  ts to the last v
dbc0: 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65  alue inserted be
dbd0: 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
dbe0: 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e   fired..**.** An
dbf0: 20 49 4e 53 45 52 54 20 74 68 61 74 20 66 61 69   INSERT that fai
dc00: 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
dc10: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
dc20: 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
dc30: 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20 61  cessful INSERT a
dc40: 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
dc50: 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
dc60: 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
dc70: 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75 73 20   routine.  Thus 
dc80: 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
dc90: 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
dca0: 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
dcb0: 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
dcc0: 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
dcd0: 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
dce0: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
dcf0: 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
dd00: 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
dd10: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
dd20: 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20   When INSERT OR 
dd30: 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
dd40: 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
dd50: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
dd60: 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
dd70: 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
dd80: 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
dd90: 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
dda0: 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
ddb0: 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
ddc0: 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
ddd0: 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
dde0: 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
ddf0: 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
de00: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
de10: 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
de20: 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75  **.** For the pu
de30: 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
de40: 6f 75 74 69 6e 65 2c 20 61 6e 20 49 4e 53 45 52  outine, an INSER
de50: 54 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  T is considered 
de60: 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
de70: 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
de80: 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
de90: 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
dea0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
deb0: 0a 2a 2a 20 7b 48 31 32 32 32 31 7d 20 54 68 65  .** {H12221} The
dec0: 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
ded0: 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 66  nsert_rowid()] f
dee0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
def0: 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 20 20 20  the rowid.**    
df00: 20 20 20 20 20 20 6f 66 20 74 68 65 20 6d 6f 73        of the mos
df10: 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73  t recent success
df20: 66 75 6c 20 49 4e 53 45 52 54 20 70 65 72 66 6f  ful INSERT perfo
df30: 72 6d 65 64 20 6f 6e 20 74 68 65 20 73 61 6d 65  rmed on the same
df40: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
df50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
df60: 6e 5d 20 61 6e 64 20 77 69 74 68 69 6e 20 74 68  n] and within th
df70: 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72  e same or higher
df80: 20 6c 65 76 65 6c 0a 2a 2a 20 20 20 20 20 20 20   level.**       
df90: 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65     trigger conte
dfa0: 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74  xt, or zero if t
dfb0: 68 65 72 65 20 68 61 76 65 20 62 65 65 6e 20 6e  here have been n
dfc0: 6f 20 71 75 61 6c 69 66 79 69 6e 67 20 69 6e 73  o qualifying ins
dfd0: 65 72 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  erts..**.** {H12
dfe0: 32 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  223} The [sqlite
dff0: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
e000: 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  wid()] function 
e010: 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20  returns the.**  
e020: 20 20 20 20 20 20 20 20 73 61 6d 65 20 76 61 6c          same val
e030: 75 65 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66  ue when called f
e040: 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 72 69  rom the same tri
e050: 67 67 65 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20  gger context.** 
e060: 20 20 20 20 20 20 20 20 20 69 6d 6d 65 64 69 61           immedia
e070: 74 65 6c 79 20 62 65 66 6f 72 65 20 61 6e 64 20  tely before and 
e080: 61 66 74 65 72 20 61 20 52 4f 4c 4c 42 41 43 4b  after a ROLLBACK
e090: 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49  ..**.** ASSUMPTI
e0a0: 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32  ONS:.**.** {A122
e0b0: 33 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74  32} If a separat
e0c0: 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
e0d0: 73 20 61 20 6e 65 77 20 49 4e 53 45 52 54 20 6f  s a new INSERT o
e0e0: 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20  n the same.**   
e0f0: 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20         database 
e100: 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
e110: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   the [sqlite3_la
e120: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
e130: 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  )].**          f
e140: 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
e150: 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
e160: 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
e170: 65 72 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 20 20  ert rowid,.**   
e180: 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20         then the 
e190: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
e1a0: 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  y [sqlite3_last_
e1b0: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20  insert_rowid()] 
e1c0: 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75  is.**          u
e1d0: 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
e1e0: 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
e1f0: 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
e200: 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 20 20  or the new.**   
e210: 20 20 20 20 20 20 20 6c 61 73 74 20 69 6e 73 65         last inse
e220: 72 74 20 72 6f 77 69 64 2e 0a 2a 2f 0a 73 71 6c  rt rowid..*/.sql
e230: 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
e240: 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
e250: 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
e260: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
e270: 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
e280: 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
e290: 65 64 20 7b 48 31 32 32 34 30 7d 20 3c 53 31 30  ed {H12240} <S10
e2a0: 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  600>.**.** This 
e2b0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
e2c0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
e2d0: 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61  atabase rows tha
e2e0: 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a  t were changed.*
e2f0: 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72  * or inserted or
e300: 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
e310: 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
e320: 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74  mpleted SQL stat
e330: 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  ement.** on the 
e340: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
e350: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
e360: 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
e370: 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20  ameter..** Only 
e380: 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65  changes that are
e390: 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66   directly specif
e3a0: 69 65 64 20 62 79 20 74 68 65 20 49 4e 53 45 52  ied by the INSER
e3b0: 54 2c 20 55 50 44 41 54 45 2c 0a 2a 2a 20 6f 72  T, UPDATE,.** or
e3c0: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
e3d0: 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20  t are counted.  
e3e0: 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  Auxiliary change
e3f0: 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74  s caused by.** t
e400: 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20  riggers are not 
e410: 63 6f 75 6e 74 65 64 2e 20 55 73 65 20 74 68 65  counted. Use the
e420: 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
e430: 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
e440: 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74  ion.** to find t
e450: 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
e460: 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 63 6c 75  of changes inclu
e470: 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75  ding changes cau
e480: 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 2e  sed by triggers.
e490: 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68  .**.** A "row ch
e4a0: 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67  ange" is a chang
e4b0: 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f  e to a single ro
e4c0: 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61  w of a single ta
e4d0: 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ble.** caused by
e4e0: 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45   an INSERT, DELE
e4f0: 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74  TE, or UPDATE st
e500: 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74  atement.  Rows t
e510: 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67  hat.** are chang
e520: 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63  ed as side effec
e530: 74 73 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f  ts of REPLACE co
e540: 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
e550: 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b  ion,.** rollback
e560: 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  , ABORT processi
e570: 6e 67 2c 20 44 52 4f 50 20 54 41 42 4c 45 2c 20  ng, DROP TABLE, 
e580: 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a  or by any other.
e590: 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f  ** mechanisms do
e5a0: 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69   not count as di
e5b0: 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
e5c0: 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ..**.** A "trigg
e5d0: 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
e5e0: 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
e5f0: 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
e600: 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
e610: 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
e620: 20 74 72 69 67 67 65 72 2e 20 20 4d 6f 73 74 20   trigger.  Most 
e630: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
e640: 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20  re.** evaluated 
e650: 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74  outside of any t
e660: 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73  rigger.  This is
e670: 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22   the "top level"
e680: 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
e690: 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67  ext.  If a trigg
e6a0: 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68  er fires from th
e6b0: 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a  e top level, a.*
e6c0: 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  * new trigger co
e6d0: 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64  ntext is entered
e6e0: 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f   for the duratio
e6f0: 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a  n of that one.**
e700: 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72   trigger.  Subtr
e710: 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75  iggers create su
e720: 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68  bcontexts for th
e730: 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a  eir duration..**
e740: 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** Calling [sql
e750: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20  ite3_exec()] or 
e760: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
e770: 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65   recursively doe
e780: 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20  s.** not create 
e790: 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  a new trigger co
e7a0: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ntext..**.** Thi
e7b0: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
e7c0: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
e7d0: 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
e7e0: 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f  ges in the.** mo
e7f0: 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
e800: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
e810: 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
e820: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  thin the same.**
e830: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
e840: 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68  ..**.** Thus, wh
e850: 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
e860: 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
e870: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
e880: 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
e890: 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
e8a0: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
e8b0: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
e8c0: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
e8d0: 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
e8e0: 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
e8f0: 2e 20 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f  .  Within the bo
e900: 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c  dy of a trigger,
e910: 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
e920: 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66  changes() interf
e930: 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ace can be calle
e940: 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
e950: 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67  mber of.** chang
e960: 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
e970: 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
e980: 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
e990: 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  , or DELETE.** s
e9a0: 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
e9b0: 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20  the body of the 
e9c0: 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
e9d0: 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75   However, the nu
e9e0: 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f  mber returned do
e9f0: 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
ea00: 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64  hanges.** caused
ea10: 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20   by subtriggers 
ea20: 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65  since those have
ea30: 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65   their own conte
ea40: 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  xt..**.** SQLite
ea50: 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
ea60: 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20  command "DELETE 
ea70: 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68  FROM table" with
ea80: 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c 61 75  out a WHERE clau
ea90: 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e  se.** by droppin
eaa0: 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67  g and recreating
eab0: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68   the table.  (Th
eac0: 69 73 20 69 73 20 6d 75 63 68 20 66 61 73 74 65  is is much faste
ead0: 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20  r than going.** 
eae0: 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65  through and dele
eaf0: 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20  ting individual 
eb00: 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68  elements from th
eb10: 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75  e table.)  Becau
eb20: 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70  se of this.** op
eb30: 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20  timization, the 
eb40: 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22 44 45  deletions in "DE
eb50: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22  LETE FROM table"
eb60: 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63 68 61   are not row cha
eb70: 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c  nges and.** will
eb80: 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20   not be counted 
eb90: 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  by the sqlite3_c
eba0: 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73 71 6c  hanges() or [sql
ebb0: 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
ebc0: 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  es()].** functio
ebd0: 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ns, regardless o
ebe0: 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
ebf0: 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65  elements that we
ec00: 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  re originally.**
ec10: 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 20   in the table.  
ec20: 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61  To get an accura
ec30: 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20  te count of the 
ec40: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64  number of rows d
ec50: 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22  eleted, use.** "
ec60: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
ec70: 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65  e WHERE 1" inste
ec80: 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ad..**.** INVARI
ec90: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
eca0: 32 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  241} The [sqlite
ecb0: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  3_changes()] fun
ecc0: 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75  ction shall retu
ecd0: 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
ece0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 77  .**          row
ecf0: 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
ed00: 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  by the most rece
ed10: 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
ed20: 45 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  E,.**          o
ed30: 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
ed40: 6e 74 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  nt on the same d
ed50: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
ed60: 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  on and.**       
ed70: 20 20 20 77 69 74 68 69 6e 20 74 68 65 20 73 61     within the sa
ed80: 6d 65 20 6f 72 20 68 69 67 68 65 72 20 74 72 69  me or higher tri
ed90: 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72  gger context, or
eda0: 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65 20 68   zero if there h
edb0: 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ave.**          
edc0: 6e 6f 74 20 62 65 65 6e 20 61 6e 79 20 71 75 61  not been any qua
edd0: 6c 69 66 79 69 6e 67 20 72 6f 77 20 63 68 61 6e  lifying row chan
ede0: 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  ges..**.** {H122
edf0: 34 33 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f  43} Statements o
ee00: 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45  f the form "DELE
ee10: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d  TE FROM tablenam
ee20: 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20  e" with no.**   
ee30: 20 20 20 20 20 20 20 57 48 45 52 45 20 63 6c 61         WHERE cla
ee40: 75 73 65 20 73 68 61 6c 6c 20 63 61 75 73 65 20  use shall cause 
ee50: 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
ee60: 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
ee70: 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
ee80: 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20 7a 65  ()] to return ze
ee90: 72 6f 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ro, regardless o
eea0: 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
eeb0: 20 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73    number of rows
eec0: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74   originally in t
eed0: 68 65 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  he table..**.** 
eee0: 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
eef0: 2a 2a 20 7b 41 31 32 32 35 32 7d 20 49 66 20 61  ** {A12252} If a
ef00: 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
ef10: 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
ef20: 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
ef30: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
ef40: 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 6c 65  *          while
ef50: 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
ef60: 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
ef70: 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
ef80: 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20  eturned.**      
ef90: 20 20 20 20 69 73 20 75 6e 70 72 65 64 69 63 74      is unpredict
efa0: 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
efb0: 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
efc0: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
efd0: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
efe0: 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
eff0: 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
f000: 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32 36   Modified {H1226
f010: 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a  0} <S10600>.**.*
f020: 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
f030: 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
f040: 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65  er of row change
f050: 73 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45  s caused by INSE
f060: 52 54 2c 0a 2a 2a 20 55 50 44 41 54 45 20 6f 72  RT,.** UPDATE or
f070: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
f080: 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61  ts since the [da
f090: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f0a0: 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a  n] was opened..*
f0b0: 2a 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c  * The count incl
f0c0: 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73  udes all changes
f0d0: 20 66 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65   from all trigge
f0e0: 72 20 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f 77  r contexts.  How
f0f0: 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75  ever,.** the cou
f100: 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
f110: 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64  ude changes used
f120: 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 52 45   to implement RE
f130: 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74  PLACE constraint
f140: 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63  s,.** do rollbac
f150: 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63  ks or ABORT proc
f160: 65 73 73 69 6e 67 2c 20 6f 72 20 44 52 4f 50 20  essing, or DROP 
f170: 74 61 62 6c 65 20 70 72 6f 63 65 73 73 69 6e 67  table processing
f180: 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67 65 73  ..** The changes
f190: 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20   are counted as 
f1a0: 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74 61 74  soon as the stat
f1b0: 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73  ement that makes
f1c0: 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70   them is.** comp
f1d0: 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20  leted (when the 
f1e0: 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  statement handle
f1f0: 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73   is passed to [s
f200: 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
f210: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
f220: 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a  inalize()])..**.
f230: 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  ** SQLite implem
f240: 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64  ents the command
f250: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
f260: 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61 20 57  ble" without a W
f270: 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62  HERE clause.** b
f280: 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72  y dropping and r
f290: 65 63 72 65 61 74 69 6e 67 20 74 68 65 20 74 61  ecreating the ta
f2a0: 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d  ble.  (This is m
f2b0: 75 63 68 20 66 61 73 74 65 72 20 74 68 61 6e 20  uch faster than 
f2c0: 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68  going.** through
f2d0: 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e   and deleting in
f2e0: 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74  dividual element
f2f0: 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65  s from the table
f300: 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  .)  Because of t
f310: 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74  his.** optimizat
f320: 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f  ion, the deletio
f330: 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52  ns in "DELETE FR
f340: 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f  OM table" are no
f350: 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e  t row changes an
f360: 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65  d.** will not be
f370: 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20   counted by the 
f380: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
f390: 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f  ) or [sqlite3_to
f3a0: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a  tal_changes()].*
f3b0: 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67  * functions, reg
f3c0: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e  ardless of the n
f3d0: 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74  umber of element
f3e0: 73 20 74 68 61 74 20 77 65 72 65 20 6f 72 69 67  s that were orig
f3f0: 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65  inally.** in the
f400: 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20   table.  To get 
f410: 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e  an accurate coun
f420: 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  t of the number 
f430: 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c  of rows deleted,
f440: 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20   use.** "DELETE 
f450: 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45  FROM table WHERE
f460: 20 31 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a   1" instead..**.
f470: 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
f480: 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
f490: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
f4a0: 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
f4b0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 31 7d 20  .**.** {H12261} 
f4c0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  The [sqlite3_tot
f4d0: 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 72 65  al_changes()] re
f4e0: 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20  turns the total 
f4f0: 6e 75 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20  number.**       
f500: 20 20 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65     of row change
f510: 73 20 63 61 75 73 65 64 20 62 79 20 49 4e 53 45  s caused by INSE
f520: 52 54 2c 20 55 50 44 41 54 45 2c 20 61 6e 64 2f  RT, UPDATE, and/
f530: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 20 20 20  or DELETE.**    
f540: 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73        statements
f550: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
f560: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f570: 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 20  n], in any.**   
f580: 20 20 20 20 20 20 20 74 72 69 67 67 65 72 20 63         trigger c
f590: 6f 6e 74 65 78 74 2c 20 73 69 6e 63 65 20 74 68  ontext, since th
f5a0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
f5b0: 63 74 69 6f 6e 20 77 61 73 20 63 72 65 61 74 65  ction was create
f5c0: 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 33  d..**.** {H12263
f5d0: 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  } Statements of 
f5e0: 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45  the form "DELETE
f5f0: 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22   FROM tablename"
f600: 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20   with no.**     
f610: 20 20 20 20 20 57 48 45 52 45 20 63 6c 61 75 73       WHERE claus
f620: 65 20 73 68 61 6c 6c 20 6e 6f 74 20 63 68 61 6e  e shall not chan
f630: 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
f640: 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  urned.**        
f650: 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 6f    by [sqlite3_to
f660: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 2e 0a  tal_changes()]..
f670: 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e  **.** ASSUMPTION
f680: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 36 34  S:.**.** {A12264
f690: 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  } If a separate 
f6a0: 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
f6b0: 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
f6c0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
f6d0: 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
f6e0: 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
f6f0: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
f700: 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
f710: 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20   the value.**   
f720: 20 20 20 20 20 20 20 72 65 74 75 72 6e 65 64 20         returned 
f730: 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
f740: 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
f750: 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
f760: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
f770: 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
f780: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
f790: 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
f7a0: 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 31  unning Query {H1
f7b0: 32 32 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a  2270} <S30500>.*
f7c0: 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
f7d0: 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
f7e0: 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
f7f0: 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
f800: 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
f810: 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
f820: 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
f830: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
f840: 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
f850: 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
f860: 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
f870: 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
f880: 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
f890: 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
f8a0: 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
f8b0: 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
f8c0: 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
f8d0: 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49  diately..**.** I
f8e0: 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
f8f0: 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
f900: 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
f910: 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
f920: 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
f930: 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
f940: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
f950: 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
f960: 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
f970: 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
f980: 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
f990: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f9a0: 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
f9b0: 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
f9c0: 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
f9d0: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
f9e0: 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
f9f0: 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
fa00: 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
fa10: 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
fa20: 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
fa30: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
fa40: 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
fa50: 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
fa60: 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
fa70: 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
fa80: 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
fa90: 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
faa0: 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
fab0: 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  * An SQL operati
fac0: 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
fad0: 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
fae0: 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
faf0: 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  RUPT]..** If the
fb00: 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
fb10: 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
fb20: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
fb30: 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
fb40: 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
fb50: 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
fb60: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
fb70: 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
fb80: 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
fb90: 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
fba0: 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20  ically..**.** A 
fbb0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
fbc0: 69 6e 74 65 72 72 75 70 74 28 29 20 68 61 73 20  interrupt() has 
fbd0: 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
fbe0: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
fbf0: 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
fc00: 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 69 6e  after sqlite3_in
fc10: 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
fc20: 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  s..**.** INVARIA
fc30: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  NTS:.**.** {H122
fc40: 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  71} The [sqlite3
fc50: 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20 69 6e  _interrupt()] in
fc60: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 66 6f 72  terface will for
fc70: 63 65 20 61 6c 6c 20 72 75 6e 6e 69 6e 67 0a 2a  ce all running.*
fc80: 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 73  *          SQL s
fc90: 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69  tatements associ
fca0: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 73 61  ated with the sa
fcb0: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
fcc0: 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
fcd0: 20 20 20 74 6f 20 68 61 6c 74 20 61 66 74 65 72     to halt after
fce0: 20 70 72 6f 63 65 73 73 69 6e 67 20 61 74 20 6d   processing at m
fcf0: 6f 73 74 20 6f 6e 65 20 61 64 64 69 74 69 6f 6e  ost one addition
fd00: 61 6c 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  al row of data..
fd10: 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 32 7d 20 41  **.** {H12272} A
fd20: 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
fd30: 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
fd40: 70 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  pted by [sqlite3
fd50: 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
fd60: 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 72            will r
fd70: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
fd80: 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20  TERRUPT]..**.** 
fd90: 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
fda0: 2a 2a 20 7b 41 31 32 32 37 39 7d 20 49 66 20 74  ** {A12279} If t
fdb0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
fdc0: 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
fdd0: 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
fde0: 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20  errupt()].**    
fdf0: 20 20 20 20 20 20 69 73 20 72 75 6e 6e 69 6e 67        is running
fe00: 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73   then bad things
fe10: 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70   will likely hap
fe20: 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  pen..*/.void sql
fe30: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
fe40: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
fe50: 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
fe60: 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
fe70: 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
fe80: 6c 65 74 65 20 7b 48 31 30 35 31 30 7d 20 3c 53  lete {H10510} <S
fe90: 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  70200>.**.** The
fea0: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
feb0: 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61  useful for comma
fec0: 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
fed0: 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
fee0: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
fef0: 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
ff00: 73 20 74 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65  s to form comple
ff10: 74 65 20 61 20 53 51 4c 20 73 74 61 74 65 6d 65  te a SQL stateme
ff20: 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
ff30: 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
ff40: 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
ff50: 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
ff60: 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
ff70: 72 20 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73  r parsing.  Thes
ff80: 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
ff90: 6e 20 74 72 75 65 20 69 66 20 74 68 65 20 69 6e  n true if the in
ffa0: 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
ffb0: 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
ffc0: 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
ffd0: 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 65 6d 65  ment.  A stateme
ffe0: 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20  nt is judged to 
fff0: 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69  be.** complete i
10000 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61  f it ends with a
10010 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e   semicolon token
10020 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 66 72   and is not a fr
10030 61 67 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43  agment of a.** C
10040 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
10050 61 74 65 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f  atement.  Semico
10060 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d  lons that are em
10070 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a  bedded within.**
10080 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73   string literals
10090 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74   or quoted ident
100a0 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63  ifier names or c
100b0 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a  omments are not.
100c0 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74  ** independent t
100d0 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20  okens (they are 
100e0 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65  part of the toke
100f0 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20  n in which they 
10100 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29  are.** embedded)
10110 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74   and thus do not
10120 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74   count as a stat
10130 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72  ement terminator
10140 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
10150 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
10160 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
10170 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
10180 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
10190 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
101a0 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
101b0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
101c0 0a 2a 2a 20 7b 48 31 30 35 31 31 7d 20 41 20 73  .** {H10511} A s
101d0 75 63 63 65 73 73 66 75 6c 20 65 76 61 6c 75 61  uccessful evalua
101e0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
101f0 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 0a  _complete()] or.
10200 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
10210 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
10220 29 5d 20 66 75 6e 63 74 69 6f 6e 73 20 73 68 61  )] functions sha
10230 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ll.**          r
10240 65 74 75 72 6e 20 61 20 6e 75 6d 65 72 69 63 20  eturn a numeric 
10250 31 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  1 if and only if
10260 20 74 68 65 20 6c 61 73 74 20 6e 6f 6e 2d 77 68   the last non-wh
10270 69 74 65 73 70 61 63 65 0a 2a 2a 20 20 20 20 20  itespace.**     
10280 20 20 20 20 20 74 6f 6b 65 6e 20 69 6e 20 74 68       token in th
10290 65 69 72 20 69 6e 70 75 74 20 69 73 20 61 20 73  eir input is a s
102a0 65 6d 69 63 6f 6c 6f 6e 20 74 68 61 74 20 69 73  emicolon that is
102b0 20 6e 6f 74 20 69 6e 20 62 65 74 77 65 65 6e 0a   not in between.
102c0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
102d0 42 45 47 49 4e 20 61 6e 64 20 45 4e 44 20 6f 66  BEGIN and END of
102e0 20 61 20 43 52 45 41 54 45 20 54 52 49 47 47 45   a CREATE TRIGGE
102f0 52 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  R statement..**.
10300 2a 2a 20 7b 48 31 30 35 31 32 7d 20 49 66 20 61  ** {H10512} If a
10310 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10320 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
10330 64 75 72 69 6e 67 20 61 6e 20 69 6e 76 6f 63 61  during an invoca
10340 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
10350 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   of [sqlite3_com
10360 70 6c 65 74 65 28 29 5d 20 6f 72 20 5b 73 71 6c  plete()] or [sql
10370 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
10380 29 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20  )] then the.**  
10390 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65 20          routine 
103a0 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51  shall return [SQ
103b0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
103c0 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
103d0 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 32 7d 20 54  **.** {A10512} T
103e0 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
103f0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
10400 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
10410 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20  terminated.**   
10420 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72         UTF-8 str
10430 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35  ing..**.** {A105
10440 31 33 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f  13} The input to
10450 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
10460 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
10470 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
10480 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54  d.**          UT
10490 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
104a0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
104b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
104c0 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
104d0 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20  char *sql);.int 
104e0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
104f0 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
10500 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
10510 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
10520 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
10530 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
10540 45 72 72 6f 72 73 20 7b 48 31 32 33 31 30 7d 20  Errors {H12310} 
10550 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S40400>.**.** T
10560 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
10570 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
10580 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20  tion that might 
10590 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
105a0 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70  ver.** an attemp
105b0 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  t is made to ope
105c0 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
105d0 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20  le that another 
105e0 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
105f0 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e  cess has locked.
10600 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 62 75  .**.** If the bu
10610 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
10620 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
10630 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
10640 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
10650 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
10660 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
10670 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
10680 68 65 20 6c 6f 63 6b 2e 20 49 66 20 74 68 65 20  he lock. If the 
10690 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
106a0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
106b0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
106c0 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20  will be invoked 
106d0 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e  with two argumen
106e0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ts..**.** The fi
106f0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
10700 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61  the handler is a
10710 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
10720 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
10730 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
10740 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
10750 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
10760 72 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  r().  The second
10770 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
10780 74 68 65 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  the handler call
10790 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62  back is the numb
107a0 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
107b0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
107c0 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
107d0 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c  voked for this l
107e0 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 49  ocking event.  I
107f0 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
10800 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
10810 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
10820 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
10830 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
10840 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
10850 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
10860 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
10870 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20  ERR_BLOCKED] is 
10880 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20  returned..** If 
10890 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
108a0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
108b0 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
108c0 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
108d0 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
108e0 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
108f0 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
10900 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
10910 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
10920 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
10930 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
10940 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
10950 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
10960 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
10970 74 65 6e 74 69 6f 6e 2e 20 49 66 20 53 51 4c 69  tention. If SQLi
10980 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
10990 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
109a0 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
109b0 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
109c0 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
109d0 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
109e0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
109f0 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c  BUSY].** or [SQL
10a00 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
10a10 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e  D] instead of in
10a20 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20  voking the busy 
10a30 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
10a40 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
10a50 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
10a60 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
10a70 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
10a80 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
10a90 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
10aa0 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
10ab0 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
10ac0 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
10ad0 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
10ae0 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
10af0 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
10b00 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
10b10 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
10b20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
10b30 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
10b40 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
10b50 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
10b60 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
10b70 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
10b80 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
10b90 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
10ba0 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
10bb0 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
10bc0 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
10bd0 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
10be0 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
10bf0 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
10c00 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
10c10 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
10c20 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
10c30 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
10c40 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
10c50 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
10c60 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
10c70 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
10c80 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
10c90 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
10ca0 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
10cb0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  eed..**.** The d
10cc0 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
10cd0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
10ce0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
10cf0 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63  BUSY] error is c
10d00 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c  onverted to [SQL
10d10 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
10d20 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  D].** when SQLit
10d30 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64  e is in the midd
10d40 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72  le of a large tr
10d50 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20  ansaction where 
10d60 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67  all the.** chang
10d70 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20  es will not fit 
10d80 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  into the in-memo
10d90 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74  ry cache.  SQLit
10da0 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64  e will.** alread
10db0 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45  y hold a RESERVE
10dc0 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61  D lock on the da
10dd0 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74  tabase file, but
10de0 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20   it needs.** to 
10df0 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63  promote this loc
10e00 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73  k to EXCLUSIVE s
10e10 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70  o that it can sp
10e20 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67  ill cache.** pag
10e30 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  es into the data
10e40 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75  base file withou
10e50 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72  t harm to concur
10e60 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e  rent.** readers.
10e70 20 20 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c    If it is unabl
10e80 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65  e to promote the
10e90 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20   lock, then the 
10ea0 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63  in-memory.** cac
10eb0 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20  he will be left 
10ec0 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65  in an inconsiste
10ed0 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20  nt state and so 
10ee0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64  the error.** cod
10ef0 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72  e is promoted fr
10f00 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c  om the relativel
10f10 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45  y benign [SQLITE
10f20 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65  _BUSY] to.** the
10f30 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51   more severe [SQ
10f40 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
10f50 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f 72  ED].  This error
10f60 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a   code promotion.
10f70 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74  ** forces an aut
10f80 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20  omatic rollback 
10f90 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20  of the changes. 
10fa0 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68   See the.** <a h
10fb0 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69  ref="/cvstrac/wi
10fc0 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46  ki?p=CorruptionF
10fd0 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
10fe0 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f  r">.** Corruptio
10ff0 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
11000 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67  ror</a> wiki pag
11010 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69  e for a discussi
11020 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69  on of why.** thi
11030 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a  s is important..
11040 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20  **.** There can 
11050 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
11060 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
11070 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
11080 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
11090 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
110a0 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
110b0 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
110c0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
110d0 74 20 68 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 65  t handler.  Note
110e0 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
110f0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
11100 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61  out()].** will a
11110 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72  lso set or clear
11120 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
11130 72 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  r..**.** INVARIA
11140 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  NTS:.**.** {H123
11150 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  11} The [sqlite3
11160 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c  _busy_handler(D,
11170 43 2c 41 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73  C,A)] function s
11180 68 61 6c 6c 20 72 65 70 6c 61 63 65 0a 2a 2a 20  hall replace.** 
11190 20 20 20 20 20 20 20 20 20 62 75 73 79 20 63 61           busy ca
111a0 6c 6c 62 61 63 6b 20 69 6e 20 74 68 65 20 5b 64  llback in the [d
111b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
111c0 6f 6e 5d 20 44 20 77 69 74 68 20 61 20 6e 65 77  on] D with a new
111d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 6e  .**          a n
111e0 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
111f0 43 20 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f  C and applicatio
11200 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 41  n data pointer A
11210 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 32 7d  ..**.** {H12312}
11220 20 4e 65 77 6c 79 20 63 72 65 61 74 65 64 20 5b   Newly created [
11230 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11240 69 6f 6e 73 5d 20 73 68 61 6c 6c 20 68 61 76 65  ions] shall have
11250 20 61 20 62 75 73 79 0a 2a 2a 20 20 20 20 20 20   a busy.**      
11260 20 20 20 20 68 61 6e 64 6c 65 72 20 6f 66 20 4e      handler of N
11270 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  ULL..**.** {H123
11280 31 34 7d 20 57 68 65 6e 20 74 77 6f 20 6f 72 20  14} When two or 
11290 6d 6f 72 65 20 5b 64 61 74 61 62 61 73 65 20 63  more [database c
112a0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 73 68 61 72  onnections] shar
112b0 65 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  e a.**          
112c0 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
112d0 73 68 61 72 65 64 5f 63 61 63 68 65 20 7c 20 63  shared_cache | c
112e0 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d 2c 0a 2a 2a  ommon cache],.**
112f0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62 75            the bu
11300 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 74  sy handler for t
11310 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
11320 65 63 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79  ection currently
11330 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
11340 20 20 20 74 68 65 20 63 61 63 68 65 20 73 68 61     the cache sha
11350 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  ll be invoked wh
11360 65 6e 20 74 68 65 20 63 61 63 68 65 20 65 6e 63  en the cache enc
11370 6f 75 6e 74 65 72 73 20 61 20 6c 6f 63 6b 2e 0a  ounters a lock..
11380 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 36 7d 20 49  **.** {H12316} I
11390 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
113a0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
113b0 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  s zero, then the
113c0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
113d0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  e.**          th
113e0 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20  at provoked the 
113f0 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 20 73 68  locking event sh
11400 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  all return [SQLI
11410 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_BUSY]..**.** 
11420 7b 48 31 32 33 31 38 7d 20 53 51 4c 69 74 65 20  {H12318} SQLite 
11430 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 73 20 74 68  shall invokes th
11440 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77  e busy handler w
11450 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
11460 73 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20 20  s which.**      
11470 20 20 20 20 61 72 65 20 61 20 63 6f 70 79 20 6f      are a copy o
11480 66 20 74 68 65 20 70 6f 69 6e 74 65 72 20 73 75  f the pointer su
11490 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 33 72  pplied by the 3r
114a0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
114b0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
114c0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
114d0 28 29 5d 20 61 6e 64 20 61 20 63 6f 75 6e 74 20  ()] and a count 
114e0 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
114f0 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20   prior.**       
11500 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f     invocations o
11510 66 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  f the busy handl
11520 65 72 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  er for the same 
11530 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 0a 2a  locking event..*
11540 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
11550 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 33 31 39 7d  :.**.** {A12319}
11560 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
11570 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
11580 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
11590 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ection.**       
115a0 20 20 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20     or [prepared 
115b0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
115c0 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
115d0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74   handler..*/.int
115e0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
115f0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
11600 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
11610 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
11620 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
11630 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 20 7b  A Busy Timeout {
11640 48 31 32 33 34 30 7d 20 3c 53 34 30 34 31 30 3e  H12340} <S40410>
11650 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
11660 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
11670 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
11680 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
11690 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
116a0 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
116b0 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
116c0 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
116d0 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64  ocked.  The hand
116e0 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65  ler.** will slee
116f0 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  p multiple times
11700 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20   until at least 
11710 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
11720 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a  s of sleeping.**
11730 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65   have accumulate
11740 64 2e 20 7b 48 31 32 33 34 33 7d 20 41 66 74 65  d. {H12343} Afte
11750 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  r "ms" milliseco
11760 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
11770 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
11780 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
11790 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
117a0 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
117b0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
117c0 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
117d0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a  ERR_BLOCKED]..**
117e0 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73  .** Calling this
117f0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
11800 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
11810 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
11820 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
11830 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
11840 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ers..**.** There
11850 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
11860 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
11870 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
11880 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
11890 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79   connection] any
118a0 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
118b0 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
118c0 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
118d0 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
118e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
118f0 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
11900 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
11910 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
11920 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
11930 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
11940 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
11950 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  NTS:.**.** {H123
11960 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  41} The [sqlite3
11970 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
11980 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
11990 6f 76 65 72 72 69 64 65 20 61 6e 79 20 70 72 69  override any pri
119a0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
119b0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
119c0 65 6f 75 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eout()] or [sqli
119d0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
119e0 28 29 5d 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20  ()] setting.**  
119f0 20 20 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73          on the s
11a00 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
11a10 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  nnection]..**.**
11a20 20 7b 48 31 32 33 34 33 7d 20 49 66 20 74 68 65   {H12343} If the
11a30 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
11a40 6f 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  o [sqlite3_busy_
11a50 74 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 6c 65  timeout()] is le
11a60 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20  ss than.**      
11a70 20 20 20 20 6f 72 20 65 71 75 61 6c 20 74 6f 20      or equal to 
11a80 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 62  zero, then the b
11a90 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c  usy handler shal
11aa0 6c 20 62 65 20 63 6c 65 61 72 65 64 20 73 6f 20  l be cleared so 
11ab0 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  that.**         
11ac0 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
11ad0 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 73 20 69  locking events i
11ae0 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75 72  mmediately retur
11af0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  n [SQLITE_BUSY].
11b00 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 34 7d 20  .**.** {H12344} 
11b10 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
11b20 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
11b30 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
11b40 20 69 73 20 61 20 70 6f 73 69 74 69 76 65 0a 2a   is a positive.*
11b50 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65  *          numbe
11b60 72 20 4e 2c 20 74 68 65 6e 20 61 20 62 75 73 79  r N, then a busy
11b70 20 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20 62   handler shall b
11b80 65 20 73 65 74 20 74 68 61 74 20 72 65 70 65 61  e set that repea
11b90 74 65 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20 20  tedly calls.**  
11ba0 20 20 20 20 20 20 20 20 74 68 65 20 78 53 6c 65          the xSle
11bb0 65 70 28 29 20 6d 65 74 68 6f 64 20 69 6e 20 74  ep() method in t
11bc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  he [sqlite3_vfs 
11bd0 7c 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 5d  | VFS interface]
11be0 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20   until.**       
11bf0 20 20 20 65 69 74 68 65 72 20 74 68 65 20 6c 6f     either the lo
11c00 63 6b 20 63 6c 65 61 72 73 20 6f 72 20 75 6e 74  ck clears or unt
11c10 69 6c 20 74 68 65 20 63 75 6d 75 6c 61 74 69 76  il the cumulativ
11c20 65 20 73 6c 65 65 70 20 74 69 6d 65 0a 2a 2a 20  e sleep time.** 
11c30 20 20 20 20 20 20 20 20 20 72 65 70 6f 72 74 65           reporte
11c40 64 20 62 61 63 6b 20 62 79 20 78 53 6c 65 65 70  d back by xSleep
11c50 28 29 20 65 78 63 65 65 64 73 20 4e 20 6d 69 6c  () exceeds N mil
11c60 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e  liseconds..*/.in
11c70 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
11c80 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
11c90 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
11ca0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
11cb0 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
11cc0 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
11cd0 69 65 73 20 7b 48 31 32 33 37 30 7d 20 3c 53 31  ies {H12370} <S1
11ce0 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  0000>.**.** Defi
11cf0 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
11d00 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
11d10 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
11d20 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
11d30 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
11d40 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
11d50 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
11d60 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
11d70 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
11d80 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
11d90 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
11da0 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
11db0 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
11dc0 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
11dd0 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
11de0 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
11df0 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
11e00 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
11e10 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
11e20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
11e30 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
11e40 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
11e50 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
11e60 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
11e70 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
11e80 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
11e90 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
11ea0 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
11eb0 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
11ec0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
11ed0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
11ee0 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
11ef0 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
11f00 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
11f10 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
11f20 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
11f30 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
11f40 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
11f50 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
11f60 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
11f70 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
11f80 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
11f90 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
11fa0 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
11fb0 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
11fc0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
11fd0 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
11fe0 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
11ff0 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
12000 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
12010 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
12020 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
12030 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
12040 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
12050 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
12060 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
12070 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
12080 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
12090 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
120a0 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
120b0 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
120c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
120d0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
120e0 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
120f0 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
12100 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
12110 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20  le()]..**.** As 
12120 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
12130 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
12140 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
12150 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
12160 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
12170 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
12180 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
12190 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
121a0 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
121b0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
121c0 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
121d0 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
121e0 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
121f0 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
12200 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
12210 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
12220 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
12230 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
12240 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
12250 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
12260 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
12270 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
12280 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
12290 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
122a0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
122b0 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
122c0 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
122d0 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
122e0 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
122f0 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
12300 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
12310 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
12320 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
12330 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
12340 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
12350 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
12360 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
12370 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
12380 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
12390 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
123a0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
123b0 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
123c0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
123d0 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
123e0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
123f0 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
12400 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
12410 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
12420 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
12430 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
12440 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
12450 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
12460 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
12470 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
12480 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
12490 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
124a0 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
124b0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
124c0 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
124d0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  2nd parameter.  
124e0 49 74 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  It returns a res
124f0 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
12500 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
12510 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
12520 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
12530 74 65 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ter the calling 
12540 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 6e  function has fin
12550 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 65 20  ished using the 
12560 72 65 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c  result, it shoul
12570 64 0a 2a 2a 20 70 61 73 73 20 74 68 65 20 70 6f  d.** pass the po
12580 69 6e 74 65 72 20 74 6f 20 74 68 65 20 72 65 73  inter to the res
12590 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 73 71 6c  ult table to sql
125a0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
125b0 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
125c0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
125d0 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
125e0 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
125f0 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
12600 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
12610 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
12620 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
12630 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
12640 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
12650 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
12660 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
12670 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
12680 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
12690 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
126a0 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
126b0 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
126c0 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
126d0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
126e0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
126f0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
12700 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
12710 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
12720 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
12730 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
12740 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
12750 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
12760 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
12770 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
12780 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
12790 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
127a0 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
127b0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
127c0 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
127d0 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
127e0 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
127f0 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
12800 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
12810 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
12820 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
12830 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
12840 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
12850 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
12860 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
12870 6f 64 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ode()] or [sqlit
12880 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
12890 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
128a0 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 31 7d 20 49  **.** {H12371} I
128b0 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  f a [sqlite3_get
128c0 5f 74 61 62 6c 65 28 29 5d 20 66 61 69 6c 73 20  _table()] fails 
128d0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
128e0 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  ion, then.**    
128f0 20 20 20 20 20 20 69 74 20 73 68 61 6c 6c 20 66        it shall f
12900 72 65 65 20 74 68 65 20 72 65 73 75 6c 74 20 74  ree the result t
12910 61 62 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73 74  able under const
12920 72 75 63 74 69 6f 6e 2c 20 61 62 6f 72 74 20 74  ruction, abort t
12930 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 71  he.**          q
12940 75 65 72 79 20 69 6e 20 70 72 6f 63 65 73 73 2c  uery in process,
12950 20 73 6b 69 70 20 61 6e 79 20 73 75 62 73 65 71   skip any subseq
12960 75 65 6e 74 20 71 75 65 72 69 65 73 2c 20 73 65  uent queries, se
12970 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  t the.**        
12980 20 20 2a 70 61 7a 52 65 73 75 6c 74 20 6f 75 74    *pazResult out
12990 70 75 74 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e  put pointer to N
129a0 55 4c 4c 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ULL and return [
129b0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
129c0 2a 0a 2a 2a 20 7b 48 31 32 33 37 33 7d 20 49 66  *.** {H12373} If
129d0 20 74 68 65 20 70 6e 43 6f 6c 75 6d 6e 20 70 61   the pnColumn pa
129e0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
129f0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
12a00 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20   is not NULL.** 
12a10 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 61 20           then a 
12a20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
12a30 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
12a40 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 73  3_get_table()] s
12a50 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  hall.**         
12a60 20 77 72 69 74 65 20 74 68 65 20 6e 75 6d 62 65   write the numbe
12a70 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
12a80 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
12a90 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
12aa0 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a 70 6e  e query into *pn
12ab0 43 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48  Column..**.** {H
12ac0 31 32 33 37 34 7d 20 49 66 20 74 68 65 20 70 6e  12374} If the pn
12ad0 52 6f 77 20 70 61 72 61 6d 65 74 65 72 20 74 6f  Row parameter to
12ae0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
12af0 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55  ble()] is not NU
12b00 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  LL.**          t
12b10 68 65 6e 20 61 20 73 75 63 63 65 73 73 66 75 6c  hen a successful
12b20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
12b30 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
12b40 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20  e()] shall.**   
12b50 20 20 20 20 20 20 20 77 72 69 74 65 73 20 74 68         writes th
12b60 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
12b70 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
12b80 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f      result set o
12b90 66 20 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f  f the query into
12ba0 20 2a 70 6e 52 6f 77 2e 0a 2a 2a 0a 2a 2a 20 7b   *pnRow..**.** {
12bb0 48 31 32 33 37 36 7d 20 41 20 73 75 63 63 65 73  H12376} A succes
12bc0 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
12bd0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  of [sqlite3_get_
12be0 74 61 62 6c 65 28 29 5d 20 74 68 61 74 20 63 6f  table()] that co
12bf0 6d 70 75 74 65 73 0a 2a 2a 20 20 20 20 20 20 20  mputes.**       
12c00 20 20 20 4e 20 72 6f 77 73 20 6f 66 20 72 65 73     N rows of res
12c10 75 6c 74 20 77 69 74 68 20 43 20 63 6f 6c 75 6d  ult with C colum
12c20 6e 73 20 70 65 72 20 72 6f 77 20 73 68 61 6c 6c  ns per row shall
12c30 20 6d 61 6b 65 20 2a 70 61 7a 52 65 73 75 6c 74   make *pazResult
12c40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69  .**          poi
12c50 6e 74 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f  nt to an array o
12c60 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 28 4e  f pointers to (N
12c70 2b 31 29 2a 43 20 73 74 72 69 6e 67 73 20 77 68  +1)*C strings wh
12c80 65 72 65 20 74 68 65 20 66 69 72 73 74 0a 2a 2a  ere the first.**
12c90 20 20 20 20 20 20 20 20 20 20 43 20 73 74 72 69            C stri
12ca0 6e 67 73 20 61 72 65 20 63 6f 6c 75 6d 6e 20 6e  ngs are column n
12cb0 61 6d 65 73 20 61 73 20 6f 62 74 61 69 6e 65 64  ames as obtained
12cc0 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20   from.**        
12cd0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d    [sqlite3_colum
12ce0 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 74 68  n_name()] and th
12cf0 65 20 72 65 73 74 20 61 72 65 20 63 6f 6c 75 6d  e rest are colum
12d00 6e 20 72 65 73 75 6c 74 20 76 61 6c 75 65 73 0a  n result values.
12d10 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62 74 61  **          obta
12d20 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
12d30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
12d40 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 39  ]..**.** {H12379
12d50 7d 20 54 68 65 20 76 61 6c 75 65 73 20 69 6e 20  } The values in 
12d60 74 68 65 20 70 61 7a 52 65 73 75 6c 74 20 61 72  the pazResult ar
12d70 72 61 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ray returned by 
12d80 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
12d90 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  le()].**        
12da0 20 20 73 68 61 6c 6c 20 72 65 6d 61 69 6e 20 76    shall remain v
12db0 61 6c 69 64 20 75 6e 74 69 6c 20 63 6c 65 61 72  alid until clear
12dc0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
12dd0 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
12de0 0a 2a 2a 20 7b 48 31 32 33 38 32 7d 20 57 68 65  .** {H12382} Whe
12df0 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
12e00 73 20 64 75 72 69 6e 67 20 65 76 61 6c 75 61 74  s during evaluat
12e10 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
12e20 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a 20  get_table()].** 
12e30 20 20 20 20 20 20 20 20 20 74 68 65 20 66 75 6e           the fun
12e40 63 74 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20  ction shall set 
12e50 2a 70 61 7a 52 65 73 75 6c 74 20 74 6f 20 4e 55  *pazResult to NU
12e60 4c 4c 2c 20 77 72 69 74 65 20 61 6e 20 65 72 72  LL, write an err
12e70 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20  or message.**   
12e80 20 20 20 20 20 20 20 69 6e 74 6f 20 6d 65 6d 6f         into memo
12e90 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
12ea0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
12eb0 28 29 5d 2c 20 6d 61 6b 65 0a 2a 2a 20 20 20 20  ()], make.**    
12ec0 20 20 20 20 20 20 2a 2a 70 7a 45 72 72 6d 73 67        **pzErrmsg
12ed0 20 70 6f 69 6e 74 20 74 6f 20 74 68 61 74 20 65   point to that e
12ee0 72 72 6f 72 20 6d 65 73 73 61 67 65 2c 20 61 6e  rror message, an
12ef0 64 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 20 20  d return a.**   
12f00 20 20 20 20 20 20 20 61 70 70 72 6f 70 72 69 61         appropria
12f10 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
12f20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
12f30 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
12f40 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
12f50 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
12f60 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
12f70 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
12f80 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
12f90 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
12fa0 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
12fb0 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
12fc0 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
12fd0 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
12fe0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
12ff0 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
13000 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
13010 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
13020 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
13030 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
13040 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
13050 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
13060 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
13070 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
13080 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
13090 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
130a0 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
130b0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
130c0 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
130d0 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
130e0 75 6e 63 74 69 6f 6e 73 20 7b 48 31 37 34 30 30  unctions {H17400
130f0 7d 20 3c 53 37 30 30 30 30 3e 3c 53 32 30 30 30  } <S70000><S2000
13100 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
13110 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
13120 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70  alikes of the "p
13130 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20  rintf()" family 
13140 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
13150 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
13160 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  d C library..**.
13170 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
13180 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
13190 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
131a0 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
131b0 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
131c0 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
131d0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
131e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
131f0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
13200 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
13210 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
13220 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
13230 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
13240 65 65 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75  ee()].  Both rou
13250 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a  tines return a.*
13260 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
13270 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
13280 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74  c()] is unable t
13290 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67  o allocate enoug
132a0 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68  h.** memory to h
132b0 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e  old the resultin
132c0 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  g string..**.** 
132d0 49 6e 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  In sqlite3_snpri
132e0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
132f0 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
13300 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
13310 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
13320 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
13330 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
13340 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
13350 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
13360 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
13370 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
13380 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
13390 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
133a0 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
133b0 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
133c0 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
133d0 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
133e0 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
133f0 29 2e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  ).  This is an.*
13400 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
13410 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
13420 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
13430 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
13440 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
13450 62 69 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c  bility.  Note al
13460 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
13470 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
13480 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
13490 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
134a0 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
134b0 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
134c0 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
134d0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
134e0 75 66 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74  uffer.  We admit
134f0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
13500 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
13510 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
13520 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
13530 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
13540 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
13550 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
13560 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
13570 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
13580 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
13590 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
135a0 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c  lity..**.** As l
135b0 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
135c0 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
135d0 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
135e0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
135f0 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
13600 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
13610 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
13620 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69  minated.  The fi
13630 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
13640 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
13650 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
13660 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
13670 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
13680 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
13690 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
136a0 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
136b0 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
136c0 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
136d0 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
136e0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
136f0 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
13700 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
13710 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
13720 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
13730 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
13740 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
13750 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
13760 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
13770 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
13780 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
13790 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
137a0 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
137b0 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e  e "%q", "%Q", an
137c0 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
137d0 2a 2a 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74  **.** The %q opt
137e0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
137f0 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62  s in that it sub
13800 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d  stitutes a null-
13810 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
13820 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72  ring from the ar
13830 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75  gument list.  Bu
13840 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65  t %q also double
13850 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61  s every '\'' cha
13860 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73  racter..** %q is
13870 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73   designed for us
13880 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e  e inside a strin
13890 67 20 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64  g literal.  By d
138a0 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
138b0 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
138c0 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
138d0 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
138e0 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
138f0 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
13900 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
13910 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
13920 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
13930 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
13940 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
13950 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
13960 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
13970 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
13980 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
13990 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
139a0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
139b0 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
139c0 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
139d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
139e0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
139f0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
13a00 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
13a10 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
13a20 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
13a30 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
13a40 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
13a50 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
13a60 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
13a70 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
13a80 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
13a90 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
13aa0 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
13ab0 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
13ac0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
13ad0 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
13ae0 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
13af0 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
13b00 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
13b10 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
13b20 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
13b30 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
13b40 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
13b50 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
13b60 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
13b70 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
13b80 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
13b90 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
13ba0 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
13bb0 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
13bc0 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
13bd0 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
13be0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
13bf0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
13c00 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
13c10 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
13c20 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
13c30 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
13c40 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
13c50 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
13c60 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
13c70 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
13c80 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
13c90 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
13ca0 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
13cb0 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
13cc0 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
13cd0 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
13ce0 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51  al..**.** The %Q
13cf0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
13d00 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20  ke %q except it 
13d10 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65  also adds single
13d20 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a   quotes around.*
13d30 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66  * the outside of
13d40 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e   the total strin
13d50 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  g.  Additionally
13d60 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  , if the paramet
13d70 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67  er in the.** arg
13d80 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20  ument list is a 
13d90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51  NULL pointer, %Q
13da0 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65   substitutes the
13db0 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69   text "NULL" (wi
13dc0 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20  thout.** single 
13dd0 71 75 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65  quotes) in place
13de0 20 6f 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f   of the %Q optio
13df0 6e 2e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  n.  So, for exam
13e00 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
13e10 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
13e20 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
13e30 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
13e40 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
13e50 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
13e60 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
13e70 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
13e80 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
13e90 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
13ea0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
13eb0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
13ec0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
13ed0 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
13ee0 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
13ef0 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
13f00 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
13f10 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
13f20 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
13f30 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
13f40 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
13f50 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
13f60 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65  g option works e
13f70 78 61 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22  xactly like "%s"
13f80 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
13f90 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
13fa0 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
13fb0 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
13fc0 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
13fd0 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
13fe0 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
13ff0 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
14000 20 73 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a   string. {END}.*
14010 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
14020 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 33 7d 20  .**.** {H17403} 
14030 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 70   The [sqlite3_mp
14040 72 69 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73 71  rintf()] and [sq
14050 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
14060 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
14070 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
14080 20 65 69 74 68 65 72 20 70 6f 69 6e 74 65 72 73   either pointers
14090 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
140a0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
140b0 73 20 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20 20  s held in.**    
140c0 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f 62         memory ob
140d0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
140e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
140f0 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  r NULL pointers 
14100 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  if.**           
14110 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
14120 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61 69  e3_malloc()] fai
14130 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30  ls..**.** {H1740
14140 36 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  6}  The [sqlite3
14150 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74  _snprintf()] int
14160 65 72 66 61 63 65 20 77 72 69 74 65 73 20 61 20  erface writes a 
14170 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
14180 2a 2a 20 20 20 20 20 20 20 20 20 20 20 55 54 46  **           UTF
14190 2d 38 20 73 74 72 69 6e 67 20 69 6e 74 6f 20 74  -8 string into t
141a0 68 65 20 62 75 66 66 65 72 20 70 6f 69 6e 74 65  he buffer pointe
141b0 64 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  d to by the seco
141c0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
141d0 20 20 20 20 20 20 20 20 20 20 70 72 6f 76 69 64            provid
141e0 65 64 20 74 68 61 74 20 74 68 65 20 66 69 72 73  ed that the firs
141f0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 67  t parameter is g
14200 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
14210 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 37 7d  ..**.** {H17407}
14220 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73    The [sqlite3_s
14230 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72  nprintf()] inter
14240 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 77 72  face does not wr
14250 69 74 65 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a 20  ite slots of.** 
14260 20 20 20 20 20 20 20 20 20 20 69 74 73 20 6f 75            its ou
14270 74 70 75 74 20 62 75 66 66 65 72 20 28 74 68 65  tput buffer (the
14280 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
14290 72 29 20 6f 75 74 73 69 64 65 20 74 68 65 20 72  r) outside the r
142a0 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  ange.**         
142b0 20 20 6f 66 20 30 20 74 68 72 6f 75 67 68 20 4e    of 0 through N
142c0 2d 31 20 28 77 68 65 72 65 20 4e 20 69 73 20 74  -1 (where N is t
142d0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
142e0 65 72 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  er).**          
142f0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
14300 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
14310 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20   string.**      
14320 20 20 20 20 20 72 65 71 75 65 73 74 65 64 20 62       requested b
14330 79 20 74 68 65 20 66 6f 72 6d 61 74 20 73 70 65  y the format spe
14340 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2f 0a 63  cification..*/.c
14350 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
14360 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
14370 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c  ,...);.char *sql
14380 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
14390 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
143a0 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  st);.char *sqlit
143b0 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
143c0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
143d0 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, ...);../*.** 
143e0 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
143f0 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
14400 79 73 74 65 6d 20 7b 48 31 37 33 30 30 7d 20 3c  ystem {H17300} <
14410 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20000>.**.** Th
14420 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 20 75  e SQLite core  u
14430 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
14440 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
14450 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
14460 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
14470 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
14480 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
14490 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
144a0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
144b0 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
144c0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
144d0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
144e0 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
144f0 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
14500 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
14510 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
14520 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
14530 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61  * The sqlite3_ma
14540 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
14550 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
14560 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
14570 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
14580 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
14590 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
145a0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
145b0 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * If sqlite3_mal
145c0 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20  loc() is unable 
145d0 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63  to obtain suffic
145e0 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d  ient free.** mem
145f0 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ory, it returns 
14600 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
14610 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   If the paramete
14620 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
14630 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
14640 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
14650 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
14660 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
14670 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
14680 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71  **.** Calling sq
14690 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
146a0 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
146b0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
146c0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
146d0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
146e0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
146f0 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
14700 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
14710 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
14720 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65   The sqlite3_fre
14730 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
14740 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
14750 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
14760 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
14770 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
14780 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
14790 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
147a0 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
147b0 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
147c0 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
147d0 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
147e0 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
147f0 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
14800 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
14810 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
14820 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
14830 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
14840 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
14850 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
14860 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
14870 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
14880 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
14890 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
148a0 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
148b0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
148c0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
148d0 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
148e0 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
148f0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
14900 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 66 72 65  ) or sqlite3_fre
14910 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  e()..**.** The s
14920 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
14930 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
14940 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
14950 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
14960 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
14970 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
14980 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  s, where N is th
14990 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
149a0 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f  meter.  The memo
149b0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
149c0 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74   be resized is t
149d0 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
149e0 6d 65 74 65 72 2e 20 20 49 66 20 74 68 65 20 66  meter.  If the f
149f0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
14a00 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
14a10 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  c().** is a NULL
14a20 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
14a30 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
14a40 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
14a50 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
14a60 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20  lloc(N) where N 
14a70 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
14a80 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
14a90 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
14aa0 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70   If the second p
14ab0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
14ac0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73  te3_realloc() is
14ad0 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
14ae0 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
14af0 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
14b00 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
14b10 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
14b20 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50  _free(P) where P
14b30 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
14b40 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
14b50 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
14b60 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
14b70 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
14b80 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
14b90 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
14ba0 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
14bb0 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
14bc0 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74  LL if sufficient
14bd0 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61   memory is unava
14be0 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20  ilable..** If M 
14bf0 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
14c00 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
14c10 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
14c20 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
14c30 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
14c40 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
14c50 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
14c60 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
14c70 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
14c80 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  e3_realloc() and
14c90 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
14ca0 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
14cb0 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 72 65  ** If sqlite3_re
14cc0 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
14cd0 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70  NULL, then the p
14ce0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  rior allocation.
14cf0 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  ** is not freed.
14d00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72  .**.** The memor
14d10 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  y returned by sq
14d20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61  lite3_malloc() a
14d30 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
14d40 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  oc().** is alway
14d50 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
14d60 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
14d70 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a  boundary. {END}.
14d80 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  **.** The defaul
14d90 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
14da0 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61   of the memory a
14db0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
14dc0 74 65 6d 20 75 73 65 73 0a 2a 2a 20 74 68 65 20  tem uses.** the 
14dd0 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
14de0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 70  c() and free() p
14df0 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 73  rovided by the s
14e00 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
14e10 79 2e 0a 2a 2a 20 7b 48 31 37 33 38 32 7d 20 48  y..** {H17382} H
14e20 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
14e30 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14e40 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
14e50 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e  _MEMORY_SIZE=<i>
14e60 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72 65 70 72 6f  NNN</i> C prepro
14e70 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 28 77 68  cessor macro (wh
14e80 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a  ere <i>NNN</i>.*
14e90 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 29  * is an integer)
14ea0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 72  , then SQLite cr
14eb0 65 61 74 65 20 61 20 73 74 61 74 69 63 20 61 72  eate a static ar
14ec0 72 61 79 20 6f 66 20 61 74 20 6c 65 61 73 74 0a  ray of at least.
14ed0 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79  ** <i>NNN</i> by
14ee0 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 20  tes in size and 
14ef0 75 73 65 73 20 74 68 61 74 20 61 72 72 61 79 20  uses that array 
14f00 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
14f10 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79  ynamic.** memory
14f20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
14f30 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64 69 74 69  s. {END}  Additi
14f40 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  onal memory allo
14f50 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a  cator options.**
14f60 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
14f70 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
14f80 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
14f90 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
14fa0 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
14fb0 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
14fc0 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
14fd0 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
14fe0 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
14ff0 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
15000 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
15010 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
15020 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
15030 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
15040 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
15050 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
15060 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
15070 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
15080 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
15090 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57  sed..**.** The W
150a0 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
150b0 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a  ace layer calls.
150c0 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
150d0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
150e0 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
150f0 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
15100 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
15110 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
15120 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
15130 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
15140 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
15150 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
15160 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
15170 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
15180 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
15190 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
151a0 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62   are detected, b
151b0 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72  ut.** they are r
151c0 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
151d0 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
151e0 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
151f0 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
15200 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
15210 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
15220 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  NTS:.**.** {H173
15230 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  03}  The [sqlite
15240 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74  3_malloc(N)] int
15250 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
15260 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65 72 20  ither a pointer 
15270 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  to.**           
15280 61 20 6e 65 77 6c 79 20 63 68 65 63 6b 65 64 2d  a newly checked-
15290 6f 75 74 20 62 6c 6f 63 6b 20 6f 66 20 61 74 20  out block of at 
152a0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 6f 66  least N bytes of
152b0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20   memory.**      
152c0 20 20 20 20 20 74 68 61 74 20 69 73 20 38 2d 62       that is 8-b
152d0 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20  yte aligned, or 
152e0 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  it returns NULL 
152f0 69 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 0a  if it is unable.
15300 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20  **           to 
15310 66 75 6c 66 69 6c 6c 20 74 68 65 20 72 65 71 75  fulfill the requ
15320 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  est..**.** {H173
15330 30 34 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  04}  The [sqlite
15340 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74  3_malloc(N)] int
15350 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
15360 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
15370 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 4e 20  .**           N 
15380 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  is less than or 
15390 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2e 0a 2a  equal to zero..*
153a0 2a 0a 2a 2a 20 7b 48 31 37 33 30 35 7d 20 20 54  *.** {H17305}  T
153b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  he [sqlite3_free
153c0 28 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (P)] interface r
153d0 65 6c 65 61 73 65 73 20 6d 65 6d 6f 72 79 20 70  eleases memory p
153e0 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20  reviously.**    
153f0 20 20 20 20 20 20 20 72 65 74 75 72 6e 65 64 20         returned 
15400 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
15410 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
15420 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a  te3_realloc()],.
15430 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6d 61 6b  **           mak
15440 69 6e 67 20 69 74 20 61 76 61 69 6c 61 62 6c 65  ing it available
15450 20 66 6f 72 20 72 65 75 73 65 2e 0a 2a 2a 0a 2a   for reuse..**.*
15460 2a 20 7b 48 31 37 33 30 36 7d 20 20 41 20 63 61  * {H17306}  A ca
15470 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ll to [sqlite3_f
15480 72 65 65 28 4e 55 4c 4c 29 5d 20 69 73 20 61 20  ree(NULL)] is a 
15490 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
154a0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 30 7d 20 20  **.** {H17310}  
154b0 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
154c0 65 33 5f 72 65 61 6c 6c 6f 63 28 30 2c 4e 29 5d  e3_realloc(0,N)]
154d0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
154e0 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20  o a call.**     
154f0 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65        to [sqlite
15500 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a  3_malloc(N)]..**
15510 0a 2a 2a 20 7b 48 31 37 33 31 32 7d 20 20 41 20  .** {H17312}  A 
15520 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
15530 5f 72 65 61 6c 6c 6f 63 28 50 2c 30 29 5d 20 69  _realloc(P,0)] i
15540 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
15550 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20  a call.**       
15560 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f      to [sqlite3_
15570 66 72 65 65 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20  free(P)]..**.** 
15580 7b 48 31 37 33 31 35 7d 20 20 54 68 65 20 53 51  {H17315}  The SQ
15590 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 5b  Lite core uses [
155a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
155b0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  ], [sqlite3_real
155c0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  loc()],.**      
155d0 20 20 20 20 20 61 6e 64 20 5b 73 71 6c 69 74 65       and [sqlite
155e0 33 5f 66 72 65 65 28 29 5d 20 66 6f 72 20 61 6c  3_free()] for al
155f0 6c 20 6f 66 20 69 74 73 20 6d 65 6d 6f 72 79 20  l of its memory 
15600 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 6e 64 0a 2a  allocation and.*
15610 2a 20 20 20 20 20 20 20 20 20 20 20 64 65 61 6c  *           deal
15620 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
15630 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 38 7d 20 20  **.** {H17318}  
15640 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  The [sqlite3_rea
15650 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69 6e 74 65 72  lloc(P,N)] inter
15660 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
15670 68 65 72 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  her a pointer.**
15680 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 61 20             to a 
15690 62 6c 6f 63 6b 20 6f 66 20 63 68 65 63 6b 65 64  block of checked
156a0 2d 6f 75 74 20 6d 65 6d 6f 72 79 20 6f 66 20 61  -out memory of a
156b0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
156c0 69 6e 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20  in size.**      
156d0 20 20 20 20 20 74 68 61 74 20 69 73 20 38 2d 62       that is 8-b
156e0 79 74 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20  yte aligned, or 
156f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
15700 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 31 7d 20 20  **.** {H17321}  
15710 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  When [sqlite3_re
15720 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75  alloc(P,N)] retu
15730 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  rns a non-NULL p
15740 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74  ointer, it first
15750 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f  .**           co
15760 70 69 65 73 20 74 68 65 20 66 69 72 73 74 20 4b  pies the first K
15770 20 62 79 74 65 73 20 6f 66 20 63 6f 6e 74 65 6e   bytes of conten
15780 74 20 66 72 6f 6d 20 50 20 69 6e 74 6f 20 74 68  t from P into th
15790 65 20 6e 65 77 6c 79 0a 2a 2a 20 20 20 20 20 20  e newly.**      
157a0 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 64 20 62       allocated b
157b0 6c 6f 63 6b 2c 20 77 68 65 72 65 20 4b 20 69 73  lock, where K is
157c0 20 74 68 65 20 6c 65 73 73 65 72 20 6f 66 20 4e   the lesser of N
157d0 20 61 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66   and the size of
157e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
157f0 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a  e buffer P..**.*
15800 2a 20 7b 48 31 37 33 32 32 7d 20 20 57 68 65 6e  * {H17322}  When
15810 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
15820 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20  c(P,N)] returns 
15830 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
15840 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a 20  er, it first.** 
15850 20 20 20 20 20 20 20 20 20 20 72 65 6c 65 61 73            releas
15860 65 73 20 74 68 65 20 62 75 66 66 65 72 20 50 2e  es the buffer P.
15870 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 33 7d 20  .**.** {H17323} 
15880 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   When [sqlite3_r
15890 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74  ealloc(P,N)] ret
158a0 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 20 62  urns NULL, the b
158b0 75 66 66 65 72 20 50 20 69 73 0a 2a 2a 20 20 20  uffer P is.**   
158c0 20 20 20 20 20 20 20 20 6e 6f 74 20 6d 6f 64 69          not modi
158d0 66 69 65 64 20 6f 72 20 72 65 6c 65 61 73 65 64  fied or released
158e0 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49  ..**.** ASSUMPTI
158f0 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33  ONS:.**.** {A173
15900 35 30 7d 20 20 54 68 65 20 70 6f 69 6e 74 65 72  50}  The pointer
15910 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
15920 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
15930 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
15940 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  loc()].**       
15950 20 20 20 20 6d 75 73 74 20 62 65 20 65 69 74 68      must be eith
15960 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
15970 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
15980 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
15990 2a 20 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f  *           invo
159a0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
159b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
159c0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
159d0 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
159e0 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20 79             not y
159f0 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  et been released
15a00 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 31 7d  ..**.** {A17351}
15a10 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
15a20 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
15a30 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
15a40 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  t of.**         
15a50 20 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d    a block of mem
15a60 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
15a70 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
15a80 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
15a90 20 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28    [sqlite3_free(
15aa0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
15ab0 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f  ealloc()]..*/.vo
15ac0 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
15ad0 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73  oc(int);.void *s
15ae0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
15af0 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  oid*, int);.void
15b00 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
15b10 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
15b20 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
15b30 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69  locator Statisti
15b40 63 73 20 7b 48 31 37 33 37 30 7d 20 3c 53 33 30  cs {H17370} <S30
15b50 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  210>.**.** SQLit
15b60 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
15b70 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
15b80 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
15b90 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
15ba0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
15bb0 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
15bc0 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
15bd0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
15be0 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
15bf0 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
15c00 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
15c10 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
15c20 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  stem..**.** INVA
15c30 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
15c40 31 37 33 37 31 7d 20 54 68 65 20 5b 73 71 6c 69  17371} The [sqli
15c50 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
15c60 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
15c70 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
15c80 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20   bytes.**       
15c90 20 20 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72     of memory cur
15ca0 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
15cb0 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
15cc0 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 0a   not freed)..**.
15cd0 2a 2a 20 7b 48 31 37 33 37 33 7d 20 54 68 65 20  ** {H17373} The 
15ce0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
15cf0 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75  highwater()] rou
15d00 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
15d10 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 20 20 20 20   maximum.**     
15d20 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 5b 73       value of [s
15d30 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
15d40 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
15d50 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
15d60 2a 2a 20 20 20 20 20 20 20 20 20 20 77 61 73 20  **          was 
15d70 6c 61 73 74 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a  last reset..**.*
15d80 2a 20 7b 48 31 37 33 37 34 7d 20 54 68 65 20 76  * {H17374} The v
15d90 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
15da0 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
15db0 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
15dc0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
15dd0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
15de0 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
15df0 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 20  ny overhead.**  
15e00 20 20 20 20 20 20 20 20 61 64 64 65 64 20 62 79          added by
15e10 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
15e20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
15e30 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15e40 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
15e50 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
15e60 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
15e70 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
15e80 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
15e90 20 20 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65           routine
15ea0 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
15eb0 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
15ec0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37  ll..**.** {H1737
15ed0 35 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  5} The memory hi
15ee0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
15ef0 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
15f00 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
15f10 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
15f20 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
15f30 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
15f40 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
15f50 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
15f60 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
15f70 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74  ighwater()] is t
15f80 72 75 65 2e 20 20 54 68 65 20 76 61 6c 75 65 20  rue.  The value 
15f90 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20  returned.**     
15fa0 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33       by [sqlite3
15fb0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
15fc0 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
15fd0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
15fe0 20 20 20 20 20 20 20 20 20 70 72 69 6f 72 20 74           prior t
15ff0 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a  o the reset..*/.
16000 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
16010 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
16020 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33  d(void);.sqlite3
16030 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
16040 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
16050 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a  int resetFlag);.
16060 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16070 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e   Pseudo-Random N
16080 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 20  umber Generator 
16090 7b 48 31 37 33 39 30 7d 20 3c 53 32 30 30 30 30  {H17390} <S20000
160a0 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63  >.**.** SQLite c
160b0 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71  ontains a high-q
160c0 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
160d0 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65  ndom number gene
160e0 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65  rator (PRNG) use
160f0 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72  d to.** select r
16100 61 6e 64 6f 6d 20 52 4f 57 49 44 73 20 77 68 65  andom ROWIDs whe
16110 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
16120 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
16130 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
16140 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
16150 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 52  rgest possible R
16160 4f 57 49 44 2e 20 20 54 68 65 20 50 52 4e 47 20  OWID.  The PRNG 
16170 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
16180 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
16190 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
161a0 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
161b0 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
161c0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
161d0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
161e0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
161f0 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
16200 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
16210 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  ** A call to thi
16220 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
16230 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
16240 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
16250 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er P..**.** The 
16260 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20  first time this 
16270 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b  routine is invok
16280 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72  ed (either inter
16290 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74  nally or by.** t
162a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20  he application) 
162b0 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64  the PRNG is seed
162c0 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
162d0 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ess obtained.** 
162e0 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
162f0 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ness method of t
16300 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
16310 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
16320 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65  .** On all subse
16330 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
16340 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  s, the pseudo-ra
16350 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
16360 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
16370 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
16380 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
16390 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
163a0 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
163b0 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  hod..**.** INVAR
163c0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
163d0 37 33 39 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  7392} The [sqlit
163e0 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 4e 2c  e3_randomness(N,
163f0 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72  P)] interface wr
16400 69 74 65 73 20 4e 20 62 79 74 65 73 20 6f 66 0a  ites N bytes of.
16410 2a 2a 20 20 20 20 20 20 20 20 20 20 68 69 67 68  **          high
16420 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
16430 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
16440 62 75 66 66 65 72 20 50 2e 0a 2a 2f 0a 76 6f 69  buffer P..*/.voi
16450 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
16460 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
16470 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
16480 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
16490 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
164a0 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32  n Callbacks {H12
164b0 35 30 30 7d 20 3c 53 37 30 31 30 30 3e 0a 2a 2a  500} <S70100>.**
164c0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
164d0 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75 74   registers a aut
164e0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
164f0 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
16500 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
16510 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
16520 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
16530 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
16540 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
16550 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
16560 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
16570 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
16580 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
16590 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
165a0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
165b0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
165c0 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
165d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
165e0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
165f0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
16600 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20    At various.** 
16610 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
16620 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
16630 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
16640 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
16650 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
16660 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
16670 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
16680 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
16690 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
166a0 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
166b0 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20  e allowed.  The 
166c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
166d0 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
166e0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
166f0 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
16700 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
16710 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
16720 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
16730 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
16740 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
16750 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
16760 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
16770 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
16780 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
16790 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
167a0 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
167b0 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
167c0 20 65 72 72 6f 72 2e 20 20 49 66 20 74 68 65 20   error.  If the 
167d0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
167e0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
167f0 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
16800 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
16810 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
16820 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
16830 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
16840 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
16850 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
16860 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
16870 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
16880 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
16890 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
168a0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
168b0 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
168c0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
168d0 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
168e0 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
168f0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
16900 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63   ok.  When the c
16910 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
16920 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
16930 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
16940 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
16950 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
16960 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
16970 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
16980 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
16990 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
169a0 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
169b0 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
169c0 6e 69 65 64 2e 20 20 49 66 20 74 68 65 20 61 75  nied.  If the au
169d0 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 69 73  thorizer code is
169e0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
169f0 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
16a00 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
16a10 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
16a20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
16a30 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
16a40 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
16a50 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
16a60 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
16a70 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
16a80 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
16a90 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
16aa0 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
16ab0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
16ac0 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
16ad0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
16ae0 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
16af0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
16b00 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
16b10 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
16b20 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
16b30 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
16b40 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
16b50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
16b60 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
16b70 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
16b80 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
16b90 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
16ba0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
16bb0 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
16bc0 63 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70  ce. The second p
16bd0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
16be0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
16bf0 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54  n integer [SQLIT
16c00 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20  E_COPY | action 
16c10 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
16c20 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74  fies.** the part
16c30 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f  icular action to
16c40 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20   be authorized. 
16c50 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
16c60 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
16c70 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
16c80 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
16c90 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
16ca0 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
16cb0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
16cc0 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
16cd0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
16ce0 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e  orized..**.** An
16cf0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
16d00 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
16d10 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
16d20 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
16d30 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
16d40 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
16d50 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
16d60 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
16d70 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
16d80 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
16d90 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
16da0 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
16db0 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
16dc0 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
16dd0 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
16de0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
16df0 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
16e00 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
16e10 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
16e20 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
16e30 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
16e40 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
16e50 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
16e60 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
16e70 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
16e80 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
16e90 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
16ea0 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
16eb0 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
16ec0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
16ed0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
16ee0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
16ef0 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
16f00 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
16f10 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
16f20 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
16f30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
16f40 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
16f50 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
16f60 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
16f70 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
16f80 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
16f90 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
16fa0 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
16fb0 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
16fc0 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
16fd0 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
16fe0 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
16ff0 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
17000 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
17010 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
17020 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
17030 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
17040 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
17050 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
17060 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
17070 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  orizer..**.** On
17080 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68  ly a single auth
17090 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e  orizer can be in
170a0 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61   place on a data
170b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
170c0 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45  ** at a time.  E
170d0 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
170e0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
170f0 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  er overrides the
17100 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c  .** previous cal
17110 6c 2e 20 20 44 69 73 61 62 6c 65 20 74 68 65 20  l.  Disable the 
17120 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
17130 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
17140 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
17150 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
17160 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
17170 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  lt..**.** Note t
17180 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
17190 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
171a0 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
171b0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
171c0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
171d0 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
171e0 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
171f0 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
17200 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
17210 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
17220 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
17230 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
17240 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 31 7d 20  .**.** {H12501} 
17250 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
17260 5f 61 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e  _authorizer(D,..
17270 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  .)] interface re
17280 67 69 73 74 65 72 73 20 61 0a 2a 2a 20 20 20 20  gisters a.**    
17290 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72        authorizer
172a0 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 64   callback with d
172b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
172c0 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  on D..**.** {H12
172d0 35 30 32 7d 20 54 68 65 20 61 75 74 68 6f 72 69  502} The authori
172e0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
172f0 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
17300 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
17310 20 20 20 20 20 20 20 20 20 20 62 65 69 6e 67 20            being 
17320 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
17330 7b 48 31 32 35 30 33 7d 20 49 66 20 74 68 65 20  {H12503} If the 
17340 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
17350 61 63 6b 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ack returns any 
17360 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
17370 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
17380 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
17390 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
173a0 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
173b0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  n.**          th
173c0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
173d0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
173e0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
173f0 20 63 61 75 73 65 64 0a 2a 2a 20 20 20 20 20 20   caused.**      
17400 20 20 20 20 74 68 65 20 61 75 74 68 6f 72 69 7a      the authoriz
17410 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72  er callback to r
17420 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69  un shall fail wi
17430 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  th an.**        
17440 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d    [SQLITE_ERROR]
17450 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
17460 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65  an appropriate e
17470 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
17480 0a 2a 2a 20 7b 48 31 32 35 30 34 7d 20 57 68 65  .** {H12504} Whe
17490 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  n the authorizer
174a0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
174b0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
174c0 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
174d0 20 20 20 20 20 20 20 20 20 64 65 73 63 72 69 62           describ
174e0 65 64 20 69 73 20 70 72 6f 63 65 73 73 65 64 20  ed is processed 
174f0 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  normally..**.** 
17500 7b 48 31 32 35 30 35 7d 20 57 68 65 6e 20 74 68  {H12505} When th
17510 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
17520 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
17530 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
17540 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
17550 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
17560 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
17570 74 20 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73  t call that caus
17580 65 64 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ed the.**       
17590 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61     authorizer ca
175a0 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68  llback to run sh
175b0 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20  all fail.**     
175c0 20 20 20 20 20 77 69 74 68 20 61 6e 20 5b 53 51       with an [SQ
175d0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f  LITE_ERROR] erro
175e0 72 20 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72  r code and an er
175f0 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20  ror message.**  
17600 20 20 20 20 20 20 20 20 65 78 70 6c 61 69 6e 69          explaini
17610 6e 67 20 74 68 61 74 20 61 63 63 65 73 73 20 69  ng that access i
17620 73 20 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  s denied..**.** 
17630 7b 48 31 32 35 30 36 7d 20 49 66 20 74 68 65 20  {H12506} If the 
17640 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20  authorizer code 
17650 28 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74  (the 2nd paramet
17660 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
17670 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  izer.**         
17680 20 63 61 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53   callback) is [S
17690 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20  QLITE_READ] and 
176a0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
176b0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
176c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
176d0 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 74 68 65  ITE_IGNORE], the
176e0 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  n the prepared s
176f0 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
17700 74 72 75 63 74 65 64 20 74 6f 0a 2a 2a 20 20 20  tructed to.**   
17710 20 20 20 20 20 20 20 69 6e 73 65 72 74 20 61 20         insert a 
17720 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
17730 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
17740 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
17750 6c 64 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20  ld have.**      
17760 20 20 20 20 62 65 65 6e 20 72 65 61 64 20 69 66      been read if
17770 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
17780 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 0a   been returned..
17790 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 37 7d 20 49  **.** {H12507} I
177a0 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
177b0 20 63 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70   code (the 2nd p
177c0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
177d0 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20  authorizer.**   
177e0 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29         callback)
177f0 20 69 73 20 61 6e 79 74 68 69 6e 67 20 6f 74 68   is anything oth
17800 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
17810 52 45 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20  READ], then.**  
17820 20 20 20 20 20 20 20 20 61 20 72 65 74 75 72 6e          a return
17830 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f   of [SQLITE_IGNO
17840 52 45 5d 20 68 61 73 20 74 68 65 20 73 61 6d 65  RE] has the same
17850 20 65 66 66 65 63 74 20 61 73 20 5b 53 51 4c 49   effect as [SQLI
17860 54 45 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_DENY]..**.** 
17870 7b 48 31 32 35 31 30 7d 20 54 68 65 20 66 69 72  {H12510} The fir
17880 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
17890 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
178a0 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
178b0 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  y of.**         
178c0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
178d0 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
178e0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
178f0 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
17900 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 31 7d  ..**.** {H12511}
17910 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
17920 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
17930 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
17940 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ger.**          
17950 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
17960 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
17970 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 70   specifies the p
17980 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
17990 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
179a0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
179b0 2a 0a 2a 2a 20 7b 48 31 32 35 31 32 7d 20 54 68  *.** {H12512} Th
179c0 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
179d0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
179e0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
179f0 20 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   are.**         
17a00 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
17a10 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
17a20 6e 74 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ntain.**        
17a30 20 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74    additional det
17a40 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
17a50 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
17a60 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  orized..**.** {H
17a70 31 32 35 32 30 7d 20 45 61 63 68 20 63 61 6c 6c  12520} Each call
17a80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65 74   to [sqlite3_set
17a90 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f  _authorizer()] o
17aa0 76 65 72 72 69 64 65 73 0a 2a 2a 20 20 20 20 20  verrides.**     
17ab0 20 20 20 20 20 61 6e 79 20 70 72 65 76 69 6f 75       any previou
17ac0 73 6c 79 20 69 6e 73 74 61 6c 6c 65 64 20 61 75  sly installed au
17ad0 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
17ae0 7b 48 31 32 35 32 31 7d 20 41 20 4e 55 4c 4c 20  {H12521} A NULL 
17af0 61 75 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73  authorizer means
17b00 20 74 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69   that no authori
17b10 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  zation.**       
17b20 20 20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69     callback is i
17b30 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nvoked..**.** {H
17b40 31 32 35 32 32 7d 20 54 68 65 20 64 65 66 61 75  12522} The defau
17b50 6c 74 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  lt authorizer is
17b60 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
17b70 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
17b80 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
17b90 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
17ba0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
17bb0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
17bc0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
17bd0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
17be0 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
17bf0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
17c00 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
17c10 74 75 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 35  turn Codes {H125
17c20 39 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a  90} <H12500>.**.
17c30 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
17c40 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
17c50 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17c60 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
17c70 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
17c80 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
17c90 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
17ca0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
17cb0 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
17cc0 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
17cd0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
17ce0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
17cf0 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
17d00 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
17d10 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
17d20 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
17d30 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
17d40 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
17d50 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  n..*/.#define SQ
17d60 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
17d70 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
17d80 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
17d90 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
17da0 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
17db0 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
17dc0 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
17dd0 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
17de0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
17df0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
17e00 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
17e10 6f 64 65 73 20 7b 48 31 32 35 35 30 7d 20 3c 48  odes {H12550} <H
17e20 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  12500>.**.** The
17e30 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
17e40 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
17e50 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
17e60 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
17e70 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
17e80 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
17e90 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20  ize certain SQL 
17ea0 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e  statement action
17eb0 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  s.  The.** secon
17ec0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
17ed0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
17ee0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
17ef0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
17f00 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20   what action is 
17f10 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
17f20 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65  .  These are the
17f30 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20   integer action 
17f40 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  codes that.** th
17f50 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
17f60 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73  lback may be pas
17f70 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
17f80 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
17f90 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
17fa0 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
17fb0 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61  on is to be.** a
17fc0 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
17fd0 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
17fe0 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75  meters to the au
17ff0 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
18000 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
18010 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
18020 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
18030 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f  nding on which o
18040 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73  f these.** codes
18050 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
18060 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18070 2e 20 20 54 68 65 20 35 74 68 20 70 61 72 61 6d  .  The 5th param
18080 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
18090 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
180a0 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
180b0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
180c0 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
180d0 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
180e0 69 63 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68  icable.  The 6th
180f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
18100 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18110 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
18120 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
18130 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
18140 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
18150 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
18160 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
18170 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
18180 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
18190 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
181a0 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
181b0 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a  l SQL code..**.*
181c0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
181d0 0a 2a 2a 20 7b 48 31 32 35 35 31 7d 20 54 68 65  .** {H12551} The
181e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
181f0 72 20 74 6f 20 61 6e 0a 2a 2a 20 20 20 20 20 20  r to an.**      
18200 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74      [sqlite3_set
18210 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
18220 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18230 6b 5d 20 69 73 20 61 6c 77 61 79 73 20 61 6e 20  k] is always an 
18240 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20  integer.**      
18250 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59      [SQLITE_COPY
18260 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f   | authorizer co
18270 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
18280 65 73 20 77 68 61 74 20 61 63 74 69 6f 6e 0a 2a  es what action.*
18290 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 62 65  *          is be
182a0 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a  ing authorized..
182b0 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 32 7d 20 54  **.** {H12552} T
182c0 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
182d0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
182e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
182f0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
18300 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 61  izer | authoriza
18310 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 5d 0a 2a  tion callback].*
18320 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20  *          will 
18330 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
18340 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
18350 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20  on which.**     
18360 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50       [SQLITE_COP
18370 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  Y | authorizer c
18380 6f 64 65 5d 20 69 73 20 75 73 65 64 20 61 73 20  ode] is used as 
18390 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
183a0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  eter..**.** {H12
183b0 35 35 33 7d 20 54 68 65 20 35 74 68 20 70 61 72  553} The 5th par
183c0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
183d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
183e0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
183f0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
18400 61 6c 6c 62 61 63 6b 5d 20 69 73 20 74 68 65 20  allback] is the 
18410 6e 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  name.**         
18420 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
18430 20 28 65 78 61 6d 70 6c 65 3a 20 22 6d 61 69 6e   (example: "main
18440 22 2c 20 22 74 65 6d 70 22 2c 20 65 74 63 2e 29  ", "temp", etc.)
18450 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 0a   if applicable..
18460 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 34 7d 20 54  **.** {H12554} T
18470 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
18480 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
18490 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74      [sqlite3_set
184a0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
184b0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
184c0 6b 5d 20 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a  k] is the name.*
184d0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
184e0 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
184f0 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
18500 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
18510 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
18520 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
18530 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
18540 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
18550 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
18560 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rom.**          
18570 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
18580 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
18590 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
185a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
185b0 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
185c0 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
185d0 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
185e0 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
185f0 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
18600 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
18610 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
18620 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18630 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
18640 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
18650 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18660 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18670 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18680 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
18690 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
186a0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
186b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
186c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
186d0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
186e0 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
186f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
18700 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18710 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18720 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
18730 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
18740 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
18750 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
18760 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18770 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
18780 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
18790 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
187a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
187b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
187c0 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
187d0 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
187e0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
187f0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
18800 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
18810 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
18820 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
18830 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
18840 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18850 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
18860 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
18870 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
18880 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
18890 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
188a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
188b0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
188c0 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
188d0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
188e0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
188f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
18900 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
18910 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
18920 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
18930 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18940 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
18950 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
18960 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
18970 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
18980 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
18990 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
189a0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
189b0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
189c0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
189d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
189e0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
189f0 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
18a00 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
18a10 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
18a20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18a30 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
18a40 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
18a50 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
18a60 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18a70 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18a80 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
18a90 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
18aa0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
18ab0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
18ac0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18ad0 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
18ae0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
18af0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
18b00 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18b10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18b20 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
18b30 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
18b40 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18b50 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18b60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18b70 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
18b80 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
18b90 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
18ba0 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
18bb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18bc0 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
18bd0 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
18be0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
18bf0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
18c00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18c10 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
18c20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
18c30 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
18c40 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18c50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18c60 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
18c70 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c       22   /* NUL
18c80 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
18c90 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
18ca0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
18cb0 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
18cc0 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
18cd0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
18ce0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
18cf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
18d00 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
18d10 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
18d20 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
18d30 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18d40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
18d50 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
18d60 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
18d70 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
18d80 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
18d90 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
18da0 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
18db0 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
18dc0 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
18dd0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
18de0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
18df0 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
18e00 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
18e10 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
18e20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18e30 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
18e40 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
18e50 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
18e60 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
18e70 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18e80 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
18e90 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
18ea0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
18eb0 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
18ec0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
18ed0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
18ee0 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
18ef0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
18f00 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
18f10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18f20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
18f30 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
18f40 20 2f 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d   /* Function Nam
18f50 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
18f60 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18f70 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
18f80 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
18f90 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
18fa0 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
18fb0 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
18fc0 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
18fd0 74 69 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c  tions {H12280} <
18fe0 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S60400>.**.** Th
18ff0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
19000 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
19010 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
19020 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
19030 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
19040 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
19050 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
19060 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ements..**.** Th
19070 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
19080 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
19090 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
190a0 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
190b0 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
190c0 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
190d0 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
190e0 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
190f0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  step()]..** The 
19100 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
19110 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
19120 6e 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74  ng of the SQL st
19130 61 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20  atement text.** 
19140 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
19150 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
19160 65 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69  ecuting.  Additi
19170 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f  onal callbacks o
19180 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
19190 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f  triggered subpro
191a0 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e  gram is entered.
191b0 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20    The callbacks 
191c0 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20  for triggers.** 
191d0 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20  contain a UTF-8 
191e0 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74  SQL comment that
191f0 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
19200 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  trigger..**.** T
19210 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
19220 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
19230 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
19240 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
19250 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
19260 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
19270 73 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20  s.  The profile 
19280 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
19290 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
192a0 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
192b0 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
192c0 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
192d0 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
192e0 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
192f0 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a  t took to run..*
19300 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
19310 5f 70 72 6f 66 69 6c 65 28 29 20 41 50 49 20 69  _profile() API i
19320 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
19330 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
19340 74 61 6c 20 61 6e 64 0a 2a 2a 20 69 73 20 73 75  tal and.** is su
19350 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
19360 6f 72 20 72 65 6d 6f 76 61 6c 20 69 6e 20 61 20  or removal in a 
19370 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 2e 0a  future release..
19380 2a 2a 0a 2a 2a 20 54 68 65 20 74 72 69 67 67 65  **.** The trigge
19390 72 20 72 65 70 6f 72 74 69 6e 67 20 66 65 61 74  r reporting feat
193a0 75 72 65 20 6f 66 20 74 68 65 20 74 72 61 63 65  ure of the trace
193b0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 6f 6e   callback is con
193c0 73 69 64 65 72 65 64 0a 2a 2a 20 65 78 70 65 72  sidered.** exper
193d0 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73  imental and is s
193e0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
193f0 20 6f 72 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66   or removal in f
19400 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
19410 2a 2a 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  ** Future versio
19420 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
19430 68 74 20 61 6c 73 6f 20 61 64 64 20 6e 65 77 20  ht also add new 
19440 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  trace callback.*
19450 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2e 0a 2a  * invocations..*
19460 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
19470 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 31 7d 20  .**.** {H12281} 
19480 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
19490 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
194a0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   by [sqlite3_tra
194b0 63 65 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20  ce()] is.**     
194c0 20 20 20 20 20 77 68 65 6e 65 76 65 72 20 61 6e       whenever an
194d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
194e0 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20 65  irst begins to e
194f0 78 65 63 75 74 65 20 61 6e 64 0a 2a 2a 20 20 20  xecute and.**   
19500 20 20 20 20 20 20 20 77 68 65 6e 65 76 65 72 20         whenever 
19510 61 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f  a trigger subpro
19520 67 72 61 6d 20 66 69 72 73 74 20 62 65 67 69 6e  gram first begin
19530 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20  s to run..**.** 
19540 7b 48 31 32 32 38 32 7d 20 45 61 63 68 20 63 61  {H12282} Each ca
19550 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  ll to [sqlite3_t
19560 72 61 63 65 28 29 5d 20 6f 76 65 72 72 69 64 65  race()] override
19570 73 20 74 68 65 20 70 72 65 76 69 6f 75 73 6c 79  s the previously
19580 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
19590 69 73 74 65 72 65 64 20 74 72 61 63 65 20 63 61  istered trace ca
195a0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48  llback..**.** {H
195b0 31 32 32 38 33 7d 20 41 20 4e 55 4c 4c 20 74 72  12283} A NULL tr
195c0 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 64 69 73  ace callback dis
195d0 61 62 6c 65 73 20 74 72 61 63 69 6e 67 2e 0a 2a  ables tracing..*
195e0 2a 0a 2a 2a 20 7b 48 31 32 32 38 34 7d 20 54 68  *.** {H12284} Th
195f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
19600 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61   to the trace ca
19610 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
19620 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
19630 74 68 65 20 70 6f 69 6e 74 65 72 20 77 68 69 63  the pointer whic
19640 68 20 77 61 73 20 74 68 65 20 33 72 64 20 61 72  h was the 3rd ar
19650 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
19660 65 33 5f 74 72 61 63 65 28 29 5d 2e 0a 2a 2a 0a  e3_trace()]..**.
19670 2a 2a 20 7b 48 31 32 32 38 35 7d 20 54 68 65 20  ** {H12285} The 
19680 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
19690 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c  to the trace cal
196a0 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20  lback is a.**   
196b0 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
196c0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
196d0 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
196e0 68 65 20 6f 72 69 67 69 6e 61 6c 20 74 65 78 74  he original text
196f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
19700 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
19710 74 20 61 73 20 69 74 20 77 61 73 20 70 61 73 73  t as it was pass
19720 65 64 20 69 6e 74 6f 20 5b 73 71 6c 69 74 65 33  ed into [sqlite3
19730 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a  _prepare_v2()].*
19740 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68  *          or th
19750 65 20 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72  e equivalent, or
19760 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20   an SQL comment 
19770 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 62  indicating the b
19780 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20  eginning.**     
19790 20 20 20 20 20 6f 66 20 61 20 74 72 69 67 67 65       of a trigge
197a0 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 0a 2a 2a  r subprogram..**
197b0 0a 2a 2a 20 7b 48 31 32 32 38 37 7d 20 54 68 65  .** {H12287} The
197c0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
197d0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
197e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
197f0 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a  e()] is invoked.
19800 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 65  **          as e
19810 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
19820 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a  t finishes..**.*
19830 2a 20 7b 48 31 32 32 38 38 7d 20 54 68 65 20 66  * {H12288} The f
19840 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
19850 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61  o the profile ca
19860 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
19870 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
19880 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
19890 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  r to [sqlite3_pr
198a0 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ofile()]..**.** 
198b0 7b 48 31 32 32 38 39 7d 20 54 68 65 20 73 65 63  {H12289} The sec
198c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
198d0 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c   the profile cal
198e0 6c 62 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20  lback is a.**   
198f0 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d         zero-term
19900 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
19910 69 6e 67 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ing that contain
19920 73 20 74 68 65 20 63 6f 6d 70 6c 65 74 65 20 74  s the complete t
19930 65 78 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ext of.**       
19940 20 20 20 74 68 65 20 53 51 4c 20 73 74 61 74 65     the SQL state
19950 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73 20 70  ment as it was p
19960 72 6f 63 65 73 73 65 64 20 62 79 20 5b 73 71 6c  rocessed by [sql
19970 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
19980 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
19990 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
199a0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 39 30 7d  ..**.** {H12290}
199b0 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
199c0 65 74 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66  eter to the prof
199d0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ile callback is 
199e0 61 6e 20 65 73 74 69 6d 61 74 65 0a 2a 2a 20 20  an estimate.**  
199f0 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6e          of the n
19a00 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63  umber of nanosec
19a10 6f 6e 64 73 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  onds of wall-clo
19a20 63 6b 20 74 69 6d 65 20 72 65 71 75 69 72 65 64  ck time required
19a30 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
19a40 72 75 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  run the SQL stat
19a50 65 6d 65 6e 74 20 66 72 6f 6d 20 73 74 61 72 74  ement from start
19a60 20 74 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a 76   to finish..*/.v
19a70 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61  oid *sqlite3_tra
19a80 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
19a90 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
19aa0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
19ab0 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  oid*);.void *sql
19ac0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
19ad0 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
19ae0 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
19af0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
19b00 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
19b10 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
19b20 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
19b30 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b  ress Callbacks {
19b40 48 31 32 39 31 30 7d 20 3c 53 36 30 34 30 30 3e  H12910} <S60400>
19b50 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
19b60 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61  ine configures a
19b70 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
19b80 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67  on - the.** prog
19b90 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20  ress callback - 
19ba0 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
19bb0 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
19bc0 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e  ing long.** runn
19bd0 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ing calls to [sq
19be0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
19bf0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
19c00 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
19c10 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41  get_table()].  A
19c20 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
19c30 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
19c40 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
19c50 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
19c60 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
19c70 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  y..**.** If the 
19c80 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
19c90 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
19ca0 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
19cb0 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
19cc0 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
19cd0 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
19ce0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
19cf0 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
19d00 20 6f 6e 20 61 20 47 55 49 20 64 69 61 6c 6f 67   on a GUI dialog
19d10 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   box..**.** INVA
19d20 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
19d30 31 32 39 31 31 7d 20 54 68 65 20 63 61 6c 6c 62  12911} The callb
19d40 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
19d50 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
19d60 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
19d70 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 20 20 20  ler().**        
19d80 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72    is invoked per
19d90 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
19da0 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
19db0 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  lls to.**       
19dc0 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70     [sqlite3_step
19dd0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ()]..**.** {H129
19de0 31 32 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73  12} The progress
19df0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
19e00 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 76  oked once for ev
19e10 65 72 79 20 4e 20 76 69 72 74 75 61 6c 0a 2a 2a  ery N virtual.**
19e20 20 20 20 20 20 20 20 20 20 20 6d 61 63 68 69 6e            machin
19e30 65 20 6f 70 63 6f 64 65 73 2c 20 77 68 65 72 65  e opcodes, where
19e40 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
19e50 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
19e60 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
19e70 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
19e80 61 6e 64 6c 65 72 28 29 5d 20 63 61 6c 6c 20 74  andler()] call t
19e90 68 61 74 20 72 65 67 69 73 74 65 72 65 64 0a 2a  hat registered.*
19ea0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63  *          the c
19eb0 61 6c 6c 62 61 63 6b 2e 20 20 49 66 20 4e 20 69  allback.  If N i
19ec0 73 20 6c 65 73 73 20 74 68 61 6e 20 31 2c 20 73  s less than 1, s
19ed0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
19ee0 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20  handler().**    
19ef0 20 20 20 20 20 20 61 63 74 73 20 61 73 20 69 66        acts as if
19f00 20 61 20 4e 55 4c 4c 20 70 72 6f 67 72 65 73 73   a NULL progress
19f10 20 68 61 6e 64 6c 65 72 20 68 61 64 20 62 65 65   handler had bee
19f20 6e 20 73 70 65 63 69 66 69 65 64 2e 0a 2a 2a 0a  n specified..**.
19f30 2a 2a 20 7b 48 31 32 39 31 33 7d 20 54 68 65 20  ** {H12913} The 
19f40 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
19f50 6b 20 69 74 73 65 6c 66 20 69 73 20 69 64 65 6e  k itself is iden
19f60 74 69 66 69 65 64 20 62 79 20 74 68 65 20 74 68  tified by the th
19f70 69 72 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ird.**          
19f80 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
19f90 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
19fa0 64 6c 65 72 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48  dler()..**.** {H
19fb0 31 32 39 31 34 7d 20 54 68 65 20 66 6f 75 72 74  12914} The fourt
19fc0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
19fd0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
19fe0 61 6e 64 6c 65 72 28 29 20 69 73 20 61 0a 2a 2a  andler() is a.**
19ff0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 70            void p
1a000 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 74 6f  ointer passed to
1a010 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
1a020 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
1a030 20 20 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68     function each
1a040 20 74 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f   time it is invo
1a050 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ked..**.** {H129
1a060 31 35 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f  15} If a call to
1a070 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1a080 5d 20 72 65 73 75 6c 74 73 20 69 6e 20 66 65 77  ] results in few
1a090 65 72 20 74 68 61 6e 20 4e 20 6f 70 63 6f 64 65  er than N opcode
1a0a0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65  s.**          be
1a0b0 69 6e 67 20 65 78 65 63 75 74 65 64 2c 20 74 68  ing executed, th
1a0c0 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  en the progress 
1a0d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76 65  callback is neve
1a0e0 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  r invoked..**.**
1a0f0 20 7b 48 31 32 39 31 36 7d 20 45 76 65 72 79 20   {H12916} Every 
1a100 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1a110 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
1a120 72 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  r()].**         
1a130 20 6f 76 65 72 77 72 69 74 65 73 20 61 6e 79 20   overwrites any 
1a140 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
1a150 74 65 72 65 64 20 70 72 6f 67 72 65 73 73 20 68  tered progress h
1a160 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  andler..**.** {H
1a170 31 32 39 31 37 7d 20 49 66 20 74 68 65 20 70 72  12917} If the pr
1a180 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
1a190 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 20  allback is NULL 
1a1a0 74 68 65 6e 20 6e 6f 20 70 72 6f 67 72 65 73 73  then no progress
1a1b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e  .**          han
1a1c0 64 6c 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2e  dler is invoked.
1a1d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 38 7d 20  .**.** {H12918} 
1a1e0 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
1a1f0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1a200 20 61 20 72 65 73 75 6c 74 20 6f 74 68 65 72 20   a result other 
1a210 74 68 61 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a 20  than 0, then.** 
1a220 20 20 20 20 20 20 20 20 20 74 68 65 20 62 65 68           the beh
1a230 61 76 69 6f 72 20 69 73 20 61 20 69 66 20 5b 73  avior is a if [s
1a240 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1a250 28 29 5d 20 68 61 64 20 62 65 65 6e 20 63 61 6c  ()] had been cal
1a260 6c 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  led..**         
1a270 20 3c 53 33 30 35 30 30 3e 0a 2a 2f 0a 76 6f 69   <S30500>.*/.voi
1a280 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
1a290 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
1a2a0 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
1a2b0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
1a2c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1a2d0 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
1a2e0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
1a2f0 69 6f 6e 20 7b 48 31 32 37 30 30 7d 20 3c 53 34  ion {H12700} <S4
1a300 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0200>.**.** Thes
1a310 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
1a320 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
1a330 73 65 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61  se file whose na
1a340 6d 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74  me is given by t
1a350 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61  he.** filename a
1a360 72 67 75 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c  rgument. The fil
1a370 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
1a380 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1a390 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
1a3a0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1a3b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1a3c0 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
1a3d0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
1a3e0 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
1a3f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1a400 29 2e 20 41 20 5b 64 61 74 61 62 61 73 65 20 63  ). A [database c
1a410 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
1a420 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
1a430 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
1a440 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
1a450 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
1a460 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
1a470 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
1a480 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
1a490 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
1a4a0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
1a4b0 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
1a4c0 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
1a4d0 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
1a4e0 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
1a4f0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1a500 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
1a510 6a 65 63 74 2e 20 49 66 20 74 68 65 20 64 61 74  ject. If the dat
1a520 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1a530 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
1a540 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
1a550 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
1a560 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
1a570 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
1a580 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
1a590 74 75 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20  turned.  The.** 
1a5a0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1a5b0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
1a5c0 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69  rrmsg16()] routi
1a5d0 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
1a5e0 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
1a5f0 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
1a600 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
1a610 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a  the error..**.**
1a620 20 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63   The default enc
1a630 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61  oding for the da
1a640 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55  tabase will be U
1a650 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74  TF-8 if.** sqlit
1a660 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
1a670 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1a680 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20  s called and.** 
1a690 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
1a6a0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
1a6b0 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  if sqlite3_open1
1a6c0 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  6() is used..**.
1a6d0 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
1a6e0 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
1a6f0 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
1a700 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
1a710 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
1a720 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
1a730 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1a740 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
1a750 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
1a760 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
1a770 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
1a780 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
1a790 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
1a7a0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
1a7b0 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
1a7c0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
1a7d0 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
1a7e0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
1a7f0 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
1a800 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
1a810 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
1a820 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
1a830 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
1a840 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20  onnection.  The 
1a850 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
1a860 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
1a870 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
1a880 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
1a890 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
1a8a0 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
1a8b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1a8c0 55 54 45 58 5d 20 66 6c 61 67 3a 0a 2a 2a 0a 2a  UTEX] flag:.**.*
1a8d0 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53  * <dl>.** <dt>[S
1a8e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
1a8f0 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
1a900 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1a910 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
1a920 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
1a930 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
1a940 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
1a950 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
1a960 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
1a970 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c  >.**.** <dt>[SQL
1a980 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1a990 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
1a9a0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1a9b0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
1a9c0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
1a9d0 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
1a9e0 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
1a9f0 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
1aa00 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
1aa10 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1aa20 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
1aa30 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
1aa40 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
1aa50 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
1aa60 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
1aa70 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a   returned.</dd>.
1aa80 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54  **.** <dt>[SQLIT
1aa90 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1aaa0 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
1aab0 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
1aac0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1aad0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
1aae0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
1aaf0 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
1ab00 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20  tes it if.** it 
1ab10 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
1ab20 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
1ab30 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
1ab40 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
1ab50 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
1ab60 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1ab70 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
1ab80 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  >.** </dl>.**.**
1ab90 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
1aba0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1abb0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
1abc0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
1abd0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
1abe0 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20  wn above or one 
1abf0 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69  of the combinati
1ac00 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
1ac10 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68  combined.** with
1ac20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1ac30 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 2c  N_NOMUTEX] flag,
1ac40 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1ac50 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
1ac60 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53  .**.** If the [S
1ac70 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1ac80 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
1ac90 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 6f 6e   then mutexes on
1aca0 20 74 68 65 0a 2a 2a 20 6f 70 65 6e 65 64 20 5b   the.** opened [
1acb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1acc0 69 6f 6e 5d 20 61 72 65 20 64 69 73 61 62 6c 65  ion] are disable
1acd0 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 61  d and the applia
1ace0 74 69 6f 6e 20 6d 75 73 74 0a 2a 2a 20 69 6e 73  tion must.** ins
1acf0 75 72 65 20 74 68 61 74 20 61 63 63 65 73 73 20  ure that access 
1ad00 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
1ad10 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
1ad20 20 69 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a   its associated.
1ad30 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
1ad40 74 65 6d 65 6e 74 73 5d 20 69 73 20 73 65 72 69  tements] is seri
1ad50 61 6c 69 7a 65 64 2e 20 20 54 68 65 20 5b 53 51  alized.  The [SQ
1ad60 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1ad70 58 5d 20 66 6c 61 67 0a 2a 2a 20 69 73 20 74 68  X] flag.** is th
1ad80 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  e default behavi
1ad90 6f 72 20 69 73 20 53 51 4c 69 74 65 20 69 73 20  or is SQLite is 
1ada0 63 6f 6e 66 69 67 75 72 65 64 20 75 73 69 6e 67  configured using
1adb0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1adc0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
1add0 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
1ade0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
1adf0 41 44 5d 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 74  AD] options.** t
1ae00 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
1ae10 67 28 29 5d 2e 20 20 54 68 65 20 5b 53 51 4c 49  g()].  The [SQLI
1ae20 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1ae30 20 66 6c 61 67 20 6f 6e 6c 79 20 6d 61 6b 65 73   flag only makes
1ae40 20 61 0a 2a 2a 20 64 69 66 66 65 72 65 6e 63 65   a.** difference
1ae50 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
1ae60 69 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 5b  in its default [
1ae70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
1ae80 52 49 41 4c 49 5a 45 44 5d 20 6d 6f 64 65 2e 0a  RIALIZED] mode..
1ae90 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c  **.** If the fil
1aea0 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
1aeb0 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
1aec0 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
1aed0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1aee0 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
1aef0 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
1af00 6f 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d  on.  This in-mem
1af10 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
1af20 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
1af30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1af40 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1af50 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
1af60 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
1af70 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
1af80 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
1af90 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
1afa0 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
1afb0 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
1afc0 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
1afd0 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
1afe0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
1aff0 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
1b000 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
1b010 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
1b020 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
1b030 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
1b040 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
1b050 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
1b060 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
1b070 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  uity..**.** If t
1b080 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
1b090 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
1b0a0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
1b0b0 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
1b0c0 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
1b0d0 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
1b0e0 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
1b0f0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
1b100 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
1b110 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
1b120 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1b130 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1b140 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  sed..**.** The f
1b150 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1b160 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1b170 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
1b180 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
1b190 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1b1a0 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
1b1b0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1b1c0 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
1b1d0 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
1b1e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1b1f0 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20  should use.  If 
1b200 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
1b210 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
1b220 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
1b230 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1b240 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1b250 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
1b260 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
1b270 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
1b280 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
1b290 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
1b2a0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
1b2b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1b2c0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1b2d0 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
1b2e0 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
1b2f0 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
1b300 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
1b310 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
1b320 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
1b330 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
1b340 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
1b350 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
1b360 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
1b370 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
1b380 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1b390 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1b3a0 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  )..**.** INVARIA
1b3b0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  NTS:.**.** {H127
1b3c0 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
1b3d0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1b3e0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
1b3f0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
1b400 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1b410 5d 20 69 6e 74 65 72 66 61 63 65 73 20 63 72 65  ] interfaces cre
1b420 61 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20  ate a new.**    
1b430 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20        [database 
1b440 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f  connection] asso
1b450 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20  ciated with.**  
1b460 20 20 20 20 20 20 20 20 74 68 65 20 64 61 74 61          the data
1b470 62 61 73 65 20 66 69 6c 65 20 67 69 76 65 6e 20  base file given 
1b480 69 6e 20 74 68 65 69 72 20 66 69 72 73 74 20 70  in their first p
1b490 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1b4a0 7b 48 31 32 37 30 32 7d 20 54 68 65 20 66 69 6c  {H12702} The fil
1b4b0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
1b4c0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1b4d0 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20   UTF-8.**       
1b4e0 20 20 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f     for [sqlite3_
1b4f0 6f 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  open()] and [sql
1b500 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
1b510 61 6e 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a  and as UTF-16.**
1b520 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65            in the
1b530 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1b540 65 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f  er for [sqlite3_
1b550 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  open16()]..**.**
1b560 20 7b 48 31 32 37 30 33 7d 20 41 20 73 75 63 63   {H12703} A succ
1b570 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f  essful invocatio
1b580 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  n of [sqlite3_op
1b590 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1b5a0 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20  open16()],.**   
1b5b0 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
1b5c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 72  e3_open_v2()] wr
1b5d0 69 74 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74  ites a pointer t
1b5e0 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20  o a new.**      
1b5f0 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
1b600 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a  nnection] into *
1b610 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ppDb..**.** {H12
1b620 37 30 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  704} The [sqlite
1b630 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1b640 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61  te3_open16()], a
1b650 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  nd.**          [
1b660 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1b670 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  )] interfaces re
1b680 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1b690 20 75 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a 2a   upon success,.*
1b6a0 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 61 6e  *          or an
1b6b0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
1b6c0 72 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69  ror code] on fai
1b6d0 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  lure..**.** {H12
1b6e0 37 30 36 7d 20 54 68 65 20 64 65 66 61 75 6c 74  706} The default
1b6f0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66   text encoding f
1b700 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73  or a new databas
1b710 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  e created using.
1b720 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1b730 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20  ite3_open()] or 
1b740 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1b750 28 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ()] will be UTF-
1b760 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 37  8..**.** {H12707
1b770 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 74 65  } The default te
1b780 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  xt encoding for 
1b790 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  a new database c
1b7a0 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
1b7b0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1b7c0 33 5f 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c 6c  3_open16()] will
1b7d0 20 62 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a   be UTF-16..**.*
1b7e0 2a 20 7b 48 31 32 37 30 39 7d 20 54 68 65 20 5b  * {H12709} The [
1b7f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c 44  sqlite3_open(F,D
1b800 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  )] interface is 
1b810 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a  equivalent to.**
1b820 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1b830 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47  e3_open_v2(F,D,G
1b840 2c 30 29 5d 20 77 68 65 72 65 20 74 68 65 20 47  ,0)] where the G
1b850 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
1b860 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
1b870 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1b880 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ]|[SQLITE_OPEN_C
1b890 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  REATE]..**.** {H
1b8a0 31 32 37 31 31 7d 20 49 66 20 74 68 65 20 47 20  12711} If the G 
1b8b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
1b8c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c  lite3_open_v2(F,
1b8d0 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73  D,G,V)] contains
1b8e0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1b8f0 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49   bit value [SQLI
1b900 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
1b910 5d 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  ] then the datab
1b920 61 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a  ase is opened.**
1b930 20 20 20 20 20 20 20 20 20 20 66 6f 72 20 72 65            for re
1b940 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ading only..**.*
1b950 2a 20 7b 48 31 32 37 31 32 7d 20 49 66 20 74 68  * {H12712} If th
1b960 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e G parameter to
1b970 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1b980 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74  2(F,D,G,V)] cont
1b990 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ains the.**     
1b9a0 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b       bit value [
1b9b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1b9c0 57 52 49 54 45 5d 20 74 68 65 6e 20 74 68 65 20  WRITE] then the 
1b9d0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1b9e0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  ed.**          r
1b9f0 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
1ba00 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
1ba10 6f 72 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f  or for reading o
1ba20 6e 6c 79 20 69 66 20 74 68 65 0a 2a 2a 20 20 20  nly if the.**   
1ba30 20 20 20 20 20 20 20 66 69 6c 65 20 69 73 20 77         file is w
1ba40 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
1ba50 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
1ba60 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  system..**.** {H
1ba70 31 32 37 31 33 7d 20 49 66 20 74 68 65 20 47 20  12713} If the G 
1ba80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
1ba90 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32 28 46 2c  lite3_open(v2(F,
1baa0 44 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74 68  D,G,V)] omits th
1bab0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69  e.**          bi
1bac0 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  t value [SQLITE_
1bad0 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64  OPEN_CREATE] and
1bae0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
1baf0 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20  es not.**       
1bb00 20 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78     previously ex
1bb10 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
1bb20 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
1bb30 20 7b 48 31 32 37 31 34 7d 20 49 66 20 74 68 65   {H12714} If the
1bb40 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   G parameter to 
1bb50 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32  [sqlite3_open(v2
1bb60 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61  (F,D,G,V)] conta
1bb70 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ins the.**      
1bb80 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53      bit value [S
1bb90 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1bba0 45 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 62  E] and the datab
1bbb0 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
1bbc0 20 20 20 20 20 20 20 20 20 70 72 65 76 69 6f 75           previou
1bbd0 73 6c 79 20 65 78 69 73 74 2c 20 74 68 65 6e 20  sly exist, then 
1bbe0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
1bbf0 64 65 20 74 6f 20 63 72 65 61 74 65 20 61 6e 64  de to create and
1bc00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 69  .**          ini
1bc10 74 69 61 6c 69 7a 65 20 74 68 65 20 64 61 74 61  tialize the data
1bc20 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  base..**.** {H12
1bc30 37 31 37 7d 20 49 66 20 74 68 65 20 66 69 6c 65  717} If the file
1bc40 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f  name argument to
1bc50 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1bc60 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
1bc70 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  16()],.**       
1bc80 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f     or [sqlite3_o
1bc90 70 65 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a 6d  pen_v2()] is ":m
1bca0 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e  emory:", then an
1bcb0 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20   private,.**    
1bcc0 20 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c 2c        ephemeral,
1bcd0 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
1bce0 61 73 65 20 69 73 20 63 72 65 61 74 65 64 20 66  ase is created f
1bcf0 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
1bd00 6e 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c  n..**          <
1bd10 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f  todo>Is SQLITE_O
1bd20 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54  PEN_CREATE|SQLIT
1bd30 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1bd40 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20   required.**    
1bd50 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33        in sqlite3
1bd60 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64  _open_v2()?</tod
1bd70 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 39  o>.**.** {H12719
1bd80 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d  } If the filenam
1bd90 65 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20  e is NULL or an 
1bda0 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
1bdb0 65 6e 20 61 20 70 72 69 76 61 74 65 2c 0a 2a 2a  en a private,.**
1bdc0 20 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65            epheme
1bdd0 72 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  ral on-disk data
1bde0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
1bdf0 61 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20  ated..**        
1be00 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54    <todo>Is SQLIT
1be10 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51  E_OPEN_CREATE|SQ
1be20 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1be30 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20  ITE required.** 
1be40 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69           in sqli
1be50 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f  te3_open_v2()?</
1be60 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  todo>.**.** {H12
1be70 37 32 31 7d 20 54 68 65 20 5b 64 61 74 61 62 61  721} The [databa
1be80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63  se connection] c
1be90 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74  reated by [sqlit
1bea0 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47  e3_open_v2(F,D,G
1beb0 2c 56 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,V)].**         
1bec0 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 5b 73   will use the [s
1bed0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1bee0 63 74 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  ct identified by
1bef0 20 74 68 65 20 56 20 70 61 72 61 6d 65 74 65 72   the V parameter
1bf00 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
1bf10 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1bf20 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1bf30 74 20 69 66 20 56 20 69 73 20 61 20 4e 55 4c 4c  t if V is a NULL
1bf40 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1bf50 7b 48 31 32 37 32 33 7d 20 54 77 6f 20 5b 64 61  {H12723} Two [da
1bf60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bf70 6e 73 5d 20 77 69 6c 6c 20 73 68 61 72 65 20 61  ns] will share a
1bf80 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 20 69 66   common cache if
1bf90 20 62 6f 74 68 20 77 65 72 65 0a 2a 2a 20 20 20   both were.**   
1bfa0 20 20 20 20 20 20 20 6f 70 65 6e 65 64 20 77 69         opened wi
1bfb0 74 68 20 74 68 65 20 73 61 6d 65 20 56 46 53 20  th the same VFS 
1bfc0 77 68 69 6c 65 20 5b 73 68 61 72 65 64 20 63 61  while [shared ca
1bfd0 63 68 65 20 6d 6f 64 65 5d 20 77 61 73 20 65 6e  che mode] was en
1bfe0 61 62 6c 65 64 20 61 6e 64 0a 2a 2a 20 20 20 20  abled and.**    
1bff0 20 20 20 20 20 20 69 66 20 62 6f 74 68 20 66 69        if both fi
1c000 6c 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72 65 20  lenames compare 
1c010 65 71 75 61 6c 20 75 73 69 6e 67 20 6d 65 6d 63  equal using memc
1c020 6d 70 28 29 20 61 66 74 65 72 20 68 61 76 69 6e  mp() after havin
1c030 67 20 62 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20  g been.**       
1c040 20 20 20 70 72 6f 63 65 73 73 65 64 20 62 79 20     processed by 
1c050 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
1c060 20 7c 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   | xFullPathname
1c070 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  ] method of the 
1c080 56 46 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  VFS..*/.int sqli
1c090 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
1c0a0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1c0b0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1c0c0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1c0d0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1c0e0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
1c0f0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1c100 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
1c110 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1c120 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
1c130 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1c140 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1c150 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
1c160 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
1c170 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1c180 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1c190 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
1c1a0 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
1c1b0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
1c1c0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
1c1d0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
1c1e0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
1c1f0 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
1c200 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
1c210 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
1c220 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
1c230 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
1c240 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
1c250 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
1c260 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
1c270 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
1c280 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
1c290 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
1c2a0 73 73 61 67 65 73 20 7b 48 31 32 38 30 30 7d 20  ssages {H12800} 
1c2b0 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60200>.**.** T
1c2c0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
1c2d0 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  de() interface r
1c2e0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
1c2f0 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
1c300 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
1c310 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
1c320 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  r the most recen
1c330 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33  t failed sqlite3
1c340 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61  _* API call.** a
1c350 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
1c360 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c370 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69  ction]. If a pri
1c380 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c  or API call fail
1c390 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f  ed.** but the mo
1c3a0 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
1c3b0 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68  ll succeeded, th
1c3c0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
1c3d0 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  rom.** sqlite3_e
1c3e0 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65  rrcode() is unde
1c3f0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
1c400 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
1c410 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
1c420 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
1c430 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
1c440 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
1c450 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
1c460 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
1c470 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
1c480 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65  pectively..** Me
1c490 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1c4a0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
1c4b0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
1c4c0 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
1c4d0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
1c4e0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
1c4f0 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
1c500 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
1c510 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
1c520 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
1c530 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
1c540 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
1c550 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
1c560 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
1c570 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
1c580 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a  ce functions..**
1c590 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
1c5a0 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
1c5b0 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
1c5c0 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
1c5d0 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
1c5e0 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
1c5f0 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
1c600 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
1c610 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
1c620 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
1c630 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
1c640 74 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  t be set..**.** 
1c650 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1c660 2a 20 7b 48 31 32 38 30 31 7d 20 54 68 65 20 5b  * {H12801} The [
1c670 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1c680 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  D)] interface re
1c690 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
1c6a0 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 72  c.**          [r
1c6b0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b  esult code] or [
1c6c0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
1c6d0 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
1c6e0 73 74 20 72 65 63 65 6e 74 6c 79 0a 2a 2a 20 20  st recently.**  
1c6f0 20 20 20 20 20 20 20 20 66 61 69 6c 65 64 20 69          failed i
1c700 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 61 73  nterface call as
1c710 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
1c720 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1c730 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a  ection] D..**.**
1c740 20 7b 48 31 32 38 30 33 7d 20 54 68 65 20 5b 73   {H12803} The [s
1c750 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29  qlite3_errmsg(D)
1c760 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  ] and [sqlite3_e
1c770 72 72 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20 20  rrmsg16(D)].**  
1c780 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
1c790 65 73 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  es return Englis
1c7a0 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 20  h-language text 
1c7b0 74 68 61 74 20 64 65 73 63 72 69 62 65 73 0a 2a  that describes.*
1c7c0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 65  *          the e
1c7d0 72 72 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73 74  rror in the most
1c7e0 6c 79 20 72 65 63 65 6e 74 6c 79 20 66 61 69 6c  ly recently fail
1c7f0 65 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c  ed interface cal
1c800 6c 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  l,.**          e
1c810 6e 63 6f 64 65 64 20 61 73 20 65 69 74 68 65 72  ncoded as either
1c820 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
1c830 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
1c840 2a 0a 2a 2a 20 7b 48 31 32 38 30 37 7d 20 54 68  *.** {H12807} Th
1c850 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
1c860 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65  ed by [sqlite3_e
1c870 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73 71  rrmsg()] and [sq
1c880 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1c890 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  ].**          ar
1c8a0 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  e valid until th
1c8b0 65 20 6e 65 78 74 20 53 51 4c 69 74 65 20 69 6e  e next SQLite in
1c8c0 74 65 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a  terface call..**
1c8d0 0a 2a 2a 20 7b 48 31 32 38 30 38 7d 20 43 61 6c  .** {H12808} Cal
1c8e0 6c 73 20 74 6f 20 41 50 49 20 72 6f 75 74 69 6e  ls to API routin
1c8f0 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 72  es that do not r
1c900 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 63  eturn an error c
1c910 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
1c920 28 65 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 74  (example: [sqlit
1c930 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
1c940 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20 20  ) do not.**     
1c950 20 20 20 20 20 63 68 61 6e 67 65 20 74 68 65 20       change the 
1c960 65 72 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d 65  error code or me
1c970 73 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 62  ssage returned b
1c980 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  y.**          [s
1c990 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1c9a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ], [sqlite3_errm
1c9b0 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  sg()], or [sqlit
1c9c0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a  e3_errmsg16()]..
1c9d0 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 39 7d 20 49  **.** {H12809} I
1c9e0 6e 74 65 72 66 61 63 65 73 20 74 68 61 74 20 61  nterfaces that a
1c9f0 72 65 20 6e 6f 74 20 61 73 73 6f 63 69 61 74 65  re not associate
1ca00 64 20 77 69 74 68 20 61 20 73 70 65 63 69 66 69  d with a specifi
1ca10 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64  c.**          [d
1ca20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ca30 6f 6e 5d 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a  on] (examples:.*
1ca40 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1ca50 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f  te3_mprintf()] o
1ca60 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  r [sqlite3_enabl
1ca70 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
1ca80 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 6f  ].**          do
1ca90 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
1caa0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
1cab0 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  by.**          [
1cac0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1cad0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  )], [sqlite3_err
1cae0 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  msg()], or [sqli
1caf0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e  te3_errmsg16()].
1cb00 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1cb10 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
1cb20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
1cb30 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
1cb40 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
1cb50 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
1cb60 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
1cb70 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1cb80 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65  REF: SQL Stateme
1cb90 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 30 30  nt Object {H1300
1cba0 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 2a 20 4b  0} <H13010>.** K
1cbb0 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
1cbc0 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
1cbd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1cbe0 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
1cbf0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
1cc00 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
1cc10 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
1cc20 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20  tement..** This 
1cc30 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75  object is variou
1cc40 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22  sly known as a "
1cc50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1cc60 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d  nt" or a.** "com
1cc70 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
1cc80 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61  ent" or simply a
1cc90 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e  s a "statement".
1cca0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  .**.** The life 
1ccb0 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
1ccc0 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
1ccd0 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
1cce0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
1ccf0 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
1cd00 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
1cd10 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1cd20 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
1cd30 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
1cd40 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
1cd50 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61  lues to [host pa
1cd60 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
1cd70 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1cd80 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
1cd90 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
1cda0 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
1cdb0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1cdc0 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
1cdd0 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
1cde0 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74  li> Reset the st
1cdf0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
1ce00 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1ce10 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
1ce20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
1ce30 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
1ce40 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
1ce50 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
1ce60 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1ce70 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1ce80 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  )]..** </ol>.**.
1ce90 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75  ** Refer to docu
1cea0 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  mentation on ind
1ceb0 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20  ividual methods 
1cec0 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69  above for additi
1ced0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1cee0 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
1cef0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
1cf00 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
1cf10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1cf20 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
1cf30 74 73 20 7b 48 31 32 37 36 30 7d 20 3c 53 32 30  ts {H12760} <S20
1cf40 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  600>.**.** This 
1cf50 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1cf60 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
1cf70 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
1cf80 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
1cf90 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
1cfa0 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
1cfb0 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
1cfc0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1cfd0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
1cfe0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
1cff0 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
1d000 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
1d010 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
1d020 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
1d030 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
1d040 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
1d050 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
1d060 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
1d070 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
1d080 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
1d090 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1d0a0 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
1d0b0 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20  that construct. 
1d0c0 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   The function re
1d0d0 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69  turns the old li
1d0e0 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  mit..**.** If th
1d0f0 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61  e new limit is a
1d100 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
1d110 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75  , the limit is u
1d120 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72  nchanged..** For
1d130 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67   the limit categ
1d140 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49  ory of SQLITE_LI
1d150 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73  MIT_XYZ there is
1d160 20 61 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a   a hard upper.**
1d170 20 62 6f 75 6e 64 20 73 65 74 20 62 79 20 61 20   bound set by a 
1d180 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70  compile-time C p
1d190 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1d1a0 6f 20 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f 4d  o named SQLITE_M
1d1b0 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28 54 68 65 20  AX_XYZ..** (The 
1d1c0 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65  "_LIMIT_" in the
1d1d0 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64   name is changed
1d1e0 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a   to "_MAX_".).**
1d1f0 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63   Attempts to inc
1d200 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
1d210 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
1d220 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
1d230 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
1d240 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
1d250 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a  pper limit..**.*
1d260 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74  * Run time limit
1d270 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
1d280 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
1d290 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
1d2a0 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
1d2b0 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
1d2c0 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
1d2d0 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
1d2e0 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
1d2f0 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
1d300 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
1d310 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
1d320 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
1d330 20 61 0a 2a 2a 20 77 65 62 62 72 6f 77 73 65 72   a.** webbrowser
1d340 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
1d350 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
1d360 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
1d370 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
1d380 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
1d390 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
1d3a0 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
1d3b0 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
1d3c0 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
1d3d0 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
1d3e0 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
1d3f0 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
1d400 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
1d410 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
1d420 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
1d430 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
1d440 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
1d450 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
1d460 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
1d470 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
1d480 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
1d490 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
1d4a0 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
1d4b0 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
1d4c0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1d4d0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
1d4e0 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
1d4f0 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
1d500 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
1d510 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
1d520 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
1d530 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
1d540 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
1d550 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
1d560 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
1d570 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
1d580 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
1d590 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
1d5a0 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
1d5b0 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a  e releases..**.*
1d5c0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1d5d0 0a 2a 2a 20 7b 48 31 32 37 36 32 7d 20 41 20 73  .** {H12762} A s
1d5e0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
1d5f0 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  o [sqlite3_limit
1d600 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56  (D,C,V)] where V
1d610 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
1d620 70 6f 73 69 74 69 76 65 20 63 68 61 6e 67 65 73  positive changes
1d630 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68   the limit on th
1d640 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72  e size of constr
1d650 75 63 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20  uct C in the.** 
1d660 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
1d670 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1d680 20 74 6f 20 74 68 65 20 6c 65 73 73 65 72 20 6f   to the lesser o
1d690 66 20 56 20 61 6e 64 20 74 68 65 20 68 61 72 64  f V and the hard
1d6a0 20 75 70 70 65 72 0a 2a 2a 20 20 20 20 20 20 20   upper.**       
1d6b0 20 20 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20     bound on the 
1d6c0 73 69 7a 65 20 6f 66 20 43 20 74 68 61 74 20 69  size of C that i
1d6d0 73 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  s set at compile
1d6e0 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  -time..**.** {H1
1d6f0 32 37 36 36 7d 20 41 20 73 75 63 63 65 73 73 66  2766} A successf
1d700 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
1d710 74 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29  te3_limit(D,C,V)
1d720 5d 20 77 68 65 72 65 20 56 20 69 73 20 6e 65 67  ] where V is neg
1d730 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  ative.**        
1d740 20 20 6c 65 61 76 65 73 20 74 68 65 20 73 74 61    leaves the sta
1d750 74 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  te of the [datab
1d760 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1d770 44 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a  D unchanged..**.
1d780 2a 2a 20 7b 48 31 32 37 36 39 7d 20 41 20 73 75  ** {H12769} A su
1d790 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1d7a0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
1d7b0 44 2c 43 2c 56 29 5d 20 72 65 74 75 72 6e 73 20  D,C,V)] returns 
1d7c0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1d7d0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d  value of the lim
1d7e0 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f  it on the size o
1d7f0 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e  f construct C in
1d800 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1d810 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1d820 63 74 69 6f 6e 5d 20 44 20 61 73 20 69 74 20 77  ction] D as it w
1d830 61 73 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  as prior to the 
1d840 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  call..*/.int sql
1d850 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
1d860 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
1d870 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
1d880 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
1d890 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
1d8a0 72 69 65 73 20 7b 48 31 32 37 39 30 7d 20 3c 48  ries {H12790} <H
1d8b0 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  12760>.** KEYWOR
1d8c0 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
1d8d0 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65  ory} {limit cate
1d8e0 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
1d8f0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
1d900 66 69 6e 65 20 76 61 72 69 6f 75 73 20 61 73 70  fine various asp
1d910 65 63 74 73 20 6f 66 20 61 20 5b 64 61 74 61 62  ects of a [datab
1d920 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
1d930 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
1d940 69 6d 69 74 65 64 20 69 6e 20 73 69 7a 65 20 62  imited in size b
1d950 79 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  y calls to [sqli
1d960 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
1d970 20 54 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   The meanings of
1d980 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
1d990 69 74 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f  its are as follo
1d9a0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ws:.**.** <dl>.*
1d9b0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1d9c0 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
1d9d0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1d9e0 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
1d9f0 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
1da00 74 61 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a  table row.<dd>.*
1da10 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1da20 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
1da30 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1da40 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
1da50 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
1da60 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ent.</dd>.**.** 
1da70 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1da80 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
1da90 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1daa0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1dab0 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
1dac0 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
1dad0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
1dae0 6f 66 20 61 20 53 45 4c 45 43 54 20 6f 72 20 74  of a SELECT or t
1daf0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1db00 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
1db10 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
1db20 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
1db30 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
1db40 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1db50 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
1db60 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
1db70 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1db80 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
1db90 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
1dba0 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
1dbb0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1dbc0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
1dbd0 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
1dbe0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1dbf0 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
1dc00 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
1dc10 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
1dc20 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1dc30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
1dc40 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
1dc50 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1dc60 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
1dc70 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
1dc80 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
1dc90 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
1dca0 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
1dcb0 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ement.</dd>.**.*
1dcc0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1dcd0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
1dce0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1dcf0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1dd00 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
1dd10 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a   function.</dd>.
1dd20 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1dd30 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
1dd40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1dd50 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1dd60 66 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  f attached datab
1dd70 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ases.</dd>.**.**
1dd80 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1dd90 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
1dda0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
1ddb0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
1ddc0 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
1ddd0 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
1dde0 74 68 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47  the LIKE or.** G
1ddf0 4c 4f 42 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  LOB operators.</
1de00 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1de10 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
1de20 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
1de30 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1de40 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72  um number of var
1de50 69 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c  iables in an SQL
1de60 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
1de70 63 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e  can.** be bound.
1de80 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  </dd>.** </dl>.*
1de90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1dea0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
1deb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1dec0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
1ded0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
1dee0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
1def0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
1df00 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
1df10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1df20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
1df30 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
1df40 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
1df50 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
1df60 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
1df70 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
1df80 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
1df90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
1dfa0 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
1dfb0 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
1dfc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
1dfd0 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
1dfe0 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
1dff0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
1e000 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
1e010 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
1e020 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
1e030 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
1e040 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
1e050 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1e060 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
1e070 20 20 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a            9../*.
1e080 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
1e090 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
1e0a0 61 74 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d  atement {H13010}
1e0b0 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59   <S10000>.** KEY
1e0c0 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
1e0d0 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
1e0e0 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
1e0f0 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
1e100 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
1e110 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
1e120 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
1e130 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
1e140 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1e150 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
1e160 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
1e170 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
1e180 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
1e190 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
1e1a0 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73  prior call to [s
1e1b0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
1e1c0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1e1d0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1e1e0 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  open16()]..**.**
1e1f0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
1e200 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
1e210 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
1e220 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
1e230 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
1e240 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
1e250 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
1e260 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
1e270 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1e280 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
1e290 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
1e2a0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
1e2b0 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
1e2c0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1e2d0 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
1e2e0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79  **.** If the nBy
1e2f0 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c  te argument is l
1e300 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74  ess than zero, t
1e310 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
1e320 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
1e330 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
1e340 74 6f 72 2e 20 49 66 20 6e 42 79 74 65 20 69 73  tor. If nByte is
1e350 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
1e360 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61  hen it is the ma
1e370 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20  ximum.** number 
1e380 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66  of  bytes read f
1e390 72 6f 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20  rom zSql.  When 
1e3a0 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
1e3b0 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53  ative, the.** zS
1e3c0 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61  ql string ends a
1e3d0 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72  t either the fir
1e3e0 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75  st '\000' or '\u
1e3f0 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20  0000' character 
1e400 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d  or.** the nByte-
1e410 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76  th byte, whichev
1e420 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20  er comes first. 
1e430 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
1e440 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ows.** that the 
1e450 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20  supplied string 
1e460 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65  is nul-terminate
1e470 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  d, then there is
1e480 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66   a small.** perf
1e490 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67  ormance advantag
1e4a0 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62  e to be gained b
1e4b0 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  y passing an nBy
1e4c0 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
1e4d0 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f  t.** is equal to
1e4e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1e4f0 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
1e500 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
1e510 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
1e520 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20   nul-terminator 
1e530 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a  bytes..**.** *pz
1e540 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
1e550 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72  point to the fir
1e560 73 74 20 62 79 74 65 20 70 61 73 74 20 74 68 65  st byte past the
1e570 20 65 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66   end of the.** f
1e580 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
1e590 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65  nt in zSql.  The
1e5a0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79  se routines only
1e5b0 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
1e5c0 73 74 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  st.** statement 
1e5d0 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
1e5e0 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
1e5f0 74 69 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d  ting to what rem
1e600 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c  ains.** uncompil
1e610 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d  ed..**.** *ppStm
1e620 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
1e630 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
1e640 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1e650 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
1e660 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
1e670 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
1e680 70 28 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20  p()].  If there 
1e690 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
1e6a0 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
1e6b0 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20  o NULL.  If the 
1e6c0 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
1e6d0 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
1e6e0 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
1e6f0 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
1e700 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
1e710 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
1e720 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 41 31   to NULL..** {A1
1e730 33 30 31 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e  3018} The callin
1e740 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
1e750 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
1e760 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
1e770 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
1e780 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
1e790 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1e7a0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
1e7b0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
1e7c0 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73  **.** On success
1e7d0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  , [SQLITE_OK] is
1e7e0 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72   returned, other
1e7f0 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
1e800 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
1e810 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1e820 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1e830 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1e840 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
1e850 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
1e860 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
1e870 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
1e880 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
1e890 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
1e8a0 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
1e8b0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1e8c0 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
1e8d0 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
1e8e0 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76  ed..** In the "v
1e8f0 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
1e900 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
1e910 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
1e920 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
1e930 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
1e940 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
1e950 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
1e960 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
1e970 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
1e980 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
1e990 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
1e9a0 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64 69 66  .** behave a dif
1e9b0 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20  ferently in two 
1e9c0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
1e9d0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74  .** <li>.** If t
1e9e0 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
1e9f0 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
1ea00 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
1ea10 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1ea20 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
1ea30 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
1ea40 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1ea50 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
1ea60 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
1ea70 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
1ea80 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
1ea90 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65  t again.  If the
1eaa0 20 73 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e   schema has chan
1eab0 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20  ged in.** a way 
1eac0 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73  that makes the s
1ead0 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67  tatement no long
1eae0 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74  er valid, [sqlit
1eaf0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
1eb00 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20  still.** return 
1eb10 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e  [SQLITE_SCHEMA].
1eb20 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65    But unlike the
1eb30 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
1eb40 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
1eb50 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61  ] is.** now a fa
1eb60 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c  tal error.  Call
1eb70 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1eb80 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e  pare_v2()] again
1eb90 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74   will not make t
1eba0 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61  he.** error go a
1ebb0 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20  way.  Note: use 
1ebc0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1ebd0 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  )] to find the t
1ebe0 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61  ext.** of the pa
1ebf0 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74  rsing error that
1ec00 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b   results in an [
1ec10 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72  SQLITE_SCHEMA] r
1ec20 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  eturn..** </li>.
1ec30 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68  **.** <li>.** Wh
1ec40 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
1ec50 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
1ec60 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
1ec70 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
1ec80 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
1ec90 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
1eca0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
1ecb0 20 20 54 68 65 20 6c 65 67 61 63 79 20 62 65 68    The legacy beh
1ecc0 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
1ecd0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
1ece0 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
1ecf0 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
1ed00 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
1ed10 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
1ed20 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20   you would have 
1ed30 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
1ed40 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1ed50 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72  3_reset()] in or
1ed60 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74  der.** to find t
1ed70 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
1ed80 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
1ed90 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
1eda0 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
1edb0 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
1edc0 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
1edd0 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
1ede0 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
1edf0 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
1ee00 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e  * </ol>.**.** IN
1ee10 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1ee20 7b 48 31 33 30 31 31 7d 20 54 68 65 20 5b 73 71  {H13011} The [sq
1ee30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 64 62  lite3_prepare(db
1ee40 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a  ,zSql,...)] and.
1ee50 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1ee60 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1ee70 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e  db,zSql,...)] in
1ee80 74 65 72 66 61 63 65 73 20 69 6e 74 65 72 70 72  terfaces interpr
1ee90 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  et the.**       
1eea0 20 20 20 74 65 78 74 20 69 6e 20 74 68 65 69 72     text in their
1eeb0 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20   zSql parameter 
1eec0 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  as UTF-8..**.** 
1eed0 7b 48 31 33 30 31 32 7d 20 54 68 65 20 5b 73 71  {H13012} The [sq
1eee0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1eef0 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e  db,zSql,...)] an
1ef00 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
1ef10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1ef20 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29  _v2(db,zSql,...)
1ef30 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74  ] interfaces int
1ef40 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20  erpret the.**   
1ef50 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74         text in t
1ef60 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65  heir zSql parame
1ef70 74 65 72 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ter as UTF-16 in
1ef80 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1ef90 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48   order..**.** {H
1efa0 31 33 30 31 33 7d 20 49 66 20 74 68 65 20 6e 42  13013} If the nB
1efb0 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  yte argument to 
1efc0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1efd0 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74  _v2(db,zSql,nByt
1efe0 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  e,...)].**      
1eff0 20 20 20 20 61 6e 64 20 69 74 73 20 76 61 72 69      and its vari
1f000 61 6e 74 73 20 69 73 20 6c 65 73 73 20 74 68 61  ants is less tha
1f010 6e 20 7a 65 72 6f 2c 20 74 68 65 20 53 51 4c 20  n zero, the SQL 
1f020 74 65 78 74 20 69 73 0a 2a 2a 20 20 20 20 20 20  text is.**      
1f030 20 20 20 20 72 65 61 64 20 66 72 6f 6d 20 7a 53      read from zS
1f040 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
1f050 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
1f060 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
1f070 2a 20 7b 48 31 33 30 31 34 7d 20 49 66 20 74 68  * {H13014} If th
1f080 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
1f090 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
1f0a0 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  pare_v2(db,zSql,
1f0b0 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  nByte,...)].**  
1f0c0 20 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20          and its 
1f0d0 76 61 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d  variants is non-
1f0e0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
1f0f0 74 20 6d 6f 73 74 20 6e 42 79 74 65 73 20 62 79  t most nBytes by
1f100 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  tes of.**       
1f110 20 20 20 53 51 4c 20 74 65 78 74 20 69 73 20 72     SQL text is r
1f120 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a 2a  ead from zSql..*
1f130 2a 0a 2a 2a 20 7b 48 31 33 30 31 35 7d 20 49 6e  *.** {H13015} In
1f140 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f150 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 50  e_v2(db,zSql,N,P
1f160 2c 70 7a 54 61 69 6c 29 5d 20 61 6e 64 20 69 74  ,pzTail)] and it
1f170 73 20 76 61 72 69 61 6e 74 73 0a 2a 2a 20 20 20  s variants.**   
1f180 20 20 20 20 20 20 20 69 66 20 74 68 65 20 7a 53         if the zS
1f190 71 6c 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  ql input text co
1f1a0 6e 74 61 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e  ntains more than
1f1b0 20 6f 6e 65 20 53 51 4c 20 73 74 61 74 65 6d 65   one SQL stateme
1f1c0 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  nt.**          a
1f1d0 6e 64 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  nd pzTail is not
1f1e0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a 54   NULL, then *pzT
1f1f0 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
1f200 6f 69 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20  oint to the.**  
1f210 20 20 20 20 20 20 20 20 66 69 72 73 74 20 62 79          first by
1f220 74 65 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  te past the end 
1f230 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
1f240 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
1f250 71 6c 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ql..**          
1f260 3c 74 6f 64 6f 3e 57 68 61 74 20 64 6f 65 73 20  <todo>What does 
1f270 2a 70 7a 54 61 69 6c 20 70 6f 69 6e 74 20 74 6f  *pzTail point to
1f280 20 69 66 20 74 68 65 72 65 20 69 73 20 6f 6e 65   if there is one
1f290 20 73 74 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f 64   statement?</tod
1f2a0 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 36  o>.**.** {H13016
1f2b0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
1f2c0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
1f2d0 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53  prepare_v2(db,zS
1f2e0 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29  ql,N,ppStmt,...)
1f2f0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
1f300 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
1f310 61 6e 74 73 20 77 72 69 74 65 73 20 69 6e 74 6f  ants writes into
1f320 20 2a 70 70 53 74 6d 74 20 61 20 70 6f 69 6e 74   *ppStmt a point
1f330 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20  er to a new.**  
1f340 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
1f350 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20  d statement] or 
1f360 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c  a pointer to NUL
1f370 4c 20 69 66 20 7a 53 71 6c 20 63 6f 6e 74 61 69  L if zSql contai
1f380 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  ns.**          n
1f390 6f 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  othing other tha
1f3a0 6e 20 77 68 69 74 65 73 70 61 63 65 20 6f 72 20  n whitespace or 
1f3b0 63 6f 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  comments..**.** 
1f3c0 7b 48 31 33 30 31 39 7d 20 54 68 65 20 5b 73 71  {H13019} The [sq
1f3d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1f3e0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
1f3f0 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 72  d its variants r
1f400 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
1f410 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72    [SQLITE_OK] or
1f420 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
1f430 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
1f440 6e 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  n failure..**.**
1f450 20 7b 48 31 33 30 32 31 7d 20 42 65 66 6f 72 65   {H13021} Before
1f460 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f470 65 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c  e(db,zSql,nByte,
1f480 70 70 53 74 6d 74 2c 70 7a 54 61 69 6c 29 5d 20  ppStmt,pzTail)] 
1f490 6f 72 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20  or its.**       
1f4a0 20 20 20 76 61 72 69 61 6e 74 73 20 72 65 74 75     variants retu
1f4b0 72 6e 73 20 61 6e 20 65 72 72 6f 72 20 28 61 6e  rns an error (an
1f4c0 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
1f4d0 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29 2c  an [SQLITE_OK]),
1f4e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1f4f0 79 20 66 69 72 73 74 20 73 65 74 20 2a 70 70 53  y first set *ppS
1f500 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  tmt to NULL..*/.
1f510 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1f520 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
1f530 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1f540 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1f550 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1f560 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
1f570 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1f580 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
1f590 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1f5a0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1f5b0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1f5c0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1f5d0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1f5e0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1f5f0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1f600 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1f610 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
1f620 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1f630 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1f640 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1f650 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
1f660 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
1f670 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1f680 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
1f690 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1f6a0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
1f6b0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
1f6c0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
1f6d0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1f6e0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1f6f0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1f700 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1f710 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1f720 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1f730 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1f740 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1f750 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
1f760 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1f770 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1f780 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1f790 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
1f7a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
1f7b0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1f7c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1f7d0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1f7e0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
1f7f0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1f800 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1f810 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
1f820 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1f830 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1f840 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1f850 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1f860 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1f870 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1f880 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1f890 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1f8a0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
1f8b0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1f8c0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1f8d0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
1f8e0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
1f8f0 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
1f900 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1f910 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1f920 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1f930 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
1f940 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1f950 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
1f960 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1f970 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1f980 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1f990 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1f9a0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1f9b0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1f9c0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1f9d0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1f9e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
1f9f0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1fa00 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1fa10 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1fa20 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
1fa30 41 50 49 52 45 46 3a 20 52 65 74 72 69 65 76 69  APIREF: Retrievi
1fa40 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
1fa50 20 7b 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30   {H13100} <H1300
1fa60 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0>.**.** This in
1fa70 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1fa80 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
1fa90 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
1faa0 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
1fab0 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
1fac0 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
1fad0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
1fae0 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  f that statement
1faf0 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
1fb00 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
1fb10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1fb20 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
1fb30 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1fb40 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1fb50 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30  TS:.**.** {H1310
1fb60 31 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61  1} If the [prepa
1fb70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70  red statement] p
1fb80 61 73 73 65 64 20 61 73 20 74 68 65 20 61 72 67  assed as the arg
1fb90 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20  ument to.**     
1fba0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 71       [sqlite3_sq
1fbb0 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65  l()] was compile
1fbc0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
1fbd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1fbe0 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  v2()] or.**     
1fbf0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72       [sqlite3_pr
1fc00 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 74  epare16_v2()], t
1fc10 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c  hen [sqlite3_sql
1fc20 28 29 5d 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  ()] returns.**  
1fc30 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65          a pointe
1fc40 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
1fc50 69 6e 61 74 65 64 20 73 74 72 69 6e 67 20 63 6f  inated string co
1fc60 6e 74 61 69 6e 69 6e 67 20 61 20 55 54 46 2d 38  ntaining a UTF-8
1fc70 20 72 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20   rendering.**   
1fc80 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 6f 72         of the or
1fc90 69 67 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 65  iginal SQL state
1fca0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ment..**.** {H13
1fcb0 31 30 32 7d 20 49 66 20 74 68 65 20 5b 70 72 65  102} If the [pre
1fcc0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1fcd0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 61   passed as the a
1fce0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20  rgument to.**   
1fcf0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1fd00 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69  sql()] was compi
1fd10 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
1fd20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1fd30 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  e()] or.**      
1fd40 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
1fd50 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20  pare16()], then 
1fd60 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20  [sqlite3_sql()] 
1fd70 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1fd80 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ointer..**.** {H
1fd90 31 33 31 30 33 7d 20 54 68 65 20 73 74 72 69 6e  13103} The strin
1fda0 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  g returned by [s
1fdb0 71 6c 69 74 65 33 5f 73 71 6c 28 53 29 5d 20 69  qlite3_sql(S)] i
1fdc0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
1fdd0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
1fde0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1fdf0 74 5d 20 53 20 69 73 20 64 65 6c 65 74 65 64 20  t] S is deleted 
1fe00 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1fe10 69 6e 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a  inalize(S)]..*/.
1fe20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1fe30 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
1fe40 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
1fe50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
1fe60 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64  ynamically Typed
1fe70 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b 48   Value Object {H
1fe80 31 35 30 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a  15000} <S20200>.
1fe90 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
1fea0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1feb0 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
1fec0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1fed0 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
1fee0 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
1fef0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
1ff00 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
1ff10 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
1ff20 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
1ff30 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
1ff40 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
1ff50 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
1ff60 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
1ff70 20 73 74 6f 72 65 73 2e 20 56 61 6c 75 65 73 20   stores. Values 
1ff80 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65  stored in sqlite
1ff90 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a  3_value objects.
1ffa0 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65  ** can be intege
1ffb0 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  rs, floating poi
1ffc0 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e  nt values, strin
1ffd0 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55  gs, BLOBs, or NU
1ffe0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c  LL..**.** An sql
1fff0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
20000 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20  t may be either 
20010 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22  "protected" or "
20020 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a  unprotected"..**
20030 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73   Some interfaces
20040 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65   require a prote
20050 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
20060 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72  ue.  Other inter
20070 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63  faces.** will ac
20080 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72  cept either a pr
20090 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e  otected or an un
200a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
200b0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72  3_value..** Ever
200c0 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
200d0 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33   accepts sqlite3
200e0 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73  _value arguments
200f0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
20100 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
20110 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65  requires a prote
20120 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
20130 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65  ue..**.** The te
20140 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20  rms "protected" 
20150 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64  and "unprotected
20160 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68  " refer to wheth
20170 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d  er or not.** a m
20180 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41  utex is held.  A
20190 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
201a0 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
201b0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
201c0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
201d0 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
201e0 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
201f0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
20200 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
20210 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
20220 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
20230 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
20240 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
20250 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
20260 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
20270 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
20280 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
20290 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
202a0 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
202b0 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
202c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
202d0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
202e0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
202f0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
20300 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
20310 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
20320 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
20330 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
20340 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
20350 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
20360 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
20370 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
20380 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
20390 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
203a0 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
203b0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
203c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
203d0 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
203e0 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
203f0 65 65 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  een between prot
20400 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
20410 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
20420 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
20430 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
20440 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
20450 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
20460 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
20470 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20  that are passed 
20480 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  as parameters in
20490 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  to the.** implem
204a0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70  entation of [app
204b0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
204c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
204d0 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a  are protected..*
204e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
204f0 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  lue object retur
20500 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
20510 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
20520 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65  )] is unprotecte
20530 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65  d..** Unprotecte
20540 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
20550 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79  objects may only
20560 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a   be used with.**
20570 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
20580 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
20590 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
205a0 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
205b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
205c0 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65   | sqlite3_value
205d0 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20  _type()] family 
205e0 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
205f0 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74   require protect
20600 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
20610 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70   objects..*/.typ
20620 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20  edef struct Mem 
20630 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a  sqlite3_value;..
20640 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20650 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  SQL Function Con
20660 74 65 78 74 20 4f 62 6a 65 63 74 20 7b 48 31 36  text Object {H16
20670 30 30 31 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  001} <S20200>.**
20680 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
20690 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
206a0 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
206b0 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
206c0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
206d0 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20  text object.  A 
206e0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71  pointer to an sq
206f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
20700 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79  ject.** is alway
20710 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
20720 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f  r to [applicatio
20730 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
20740 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65  nctions]..** The
20750 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
20760 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
20770 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
20780 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a   will pass this.
20790 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75  ** pointer throu
207a0 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f  gh into calls to
207b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
207c0 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72  _int | sqlite3_r
207d0 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  esult()],.** [sq
207e0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
207f0 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c  context()], [sql
20800 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
20810 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ],.** [sqlite3_c
20820 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
20830 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65  ()], [sqlite3_ge
20840 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a  t_auxdata()],.**
20850 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33   and/or [sqlite3
20860 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e  _set_auxdata()].
20870 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
20880 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ct sqlite3_conte
20890 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt sqlite3_conte
208a0 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  xt;../*.** CAPI3
208b0 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c  REF: Binding Val
208c0 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
208d0 53 74 61 74 65 6d 65 6e 74 73 20 7b 48 31 33 35  Statements {H135
208e0 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 20  00} <S70300>.** 
208f0 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20  KEYWORDS: {host 
20900 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74  parameter} {host
20910 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f   parameters} {ho
20920 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
20930 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  e}.** KEYWORDS: 
20940 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20  {SQL parameter} 
20950 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d  {SQL parameters}
20960 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   {parameter bind
20970 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ing}.**.** In th
20980 65 20 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e  e SQL strings in
20990 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
209a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
209b0 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
209c0 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
209d0 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
209e0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e   parameter in on
209f0 65 20 6f 66 20 74 68 65 73 65 20 66 6f 72 6d 73  e of these forms
20a00 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
20a10 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20  <li>  ?.** <li> 
20a20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a   ?NNN.** <li>  :
20a30 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56  VVV.** <li>  @VV
20a40 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a  V.** <li>  $VVV.
20a50 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
20a60 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
20a70 66 6f 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76  forms shown abov
20a80 65 20 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65  e NNN is an inte
20a90 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
20aa0 61 6e 64 20 56 56 56 20 69 73 20 61 6e 20 61 6c  and VVV is an al
20ab0 70 68 61 2d 6e 75 6d 65 72 69 63 20 70 61 72 61  pha-numeric para
20ac0 6d 65 74 65 72 20 6e 61 6d 65 2e 20 54 68 65 20  meter name. The 
20ad0 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a  values of these.
20ae0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  ** parameters (a
20af0 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
20b00 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
20b10 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  " or "SQL parame
20b20 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
20b30 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
20b40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
20b50 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
20b60 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   here..**.** The
20b70 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
20b80 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
20b90 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
20ba0 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
20bb0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
20bc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
20bd0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
20be0 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
20bf0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
20c00 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
20c10 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
20c20 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
20c30 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
20c40 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
20c50 73 65 74 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 74  set..** The left
20c60 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
20c70 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
20c80 6f 66 20 31 2e 20 20 57 68 65 6e 20 74 68 65 20  of 1.  When the 
20c90 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51  same named.** SQ
20ca0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  L parameter is u
20cb0 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  sed more than on
20cc0 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ce, second and s
20cd0 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63  ubsequent.** occ
20ce0 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68  urrences have th
20cf0 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20  e same index as 
20d00 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
20d10 65 6e 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6e 64  ence..** The ind
20d20 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
20d30 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
20d40 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
20d50 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
20d60 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
20d70 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
20d80 73 69 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65  sired.  The inde
20d90 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
20da0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
20db0 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
20dc0 2a 2a 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  ** The NNN value
20dd0 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
20de0 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
20df0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
20e00 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
20e10 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
20e20 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
20e30 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
20e40 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61  *.** The third a
20e50 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
20e60 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
20e70 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
20e80 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 72 6f  *.** In those ro
20e90 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
20ea0 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
20eb0 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
20ec0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
20ed0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
20ee0 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
20ef0 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
20f00 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
20f10 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
20f20 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
20f30 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
20f40 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
20f50 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20  * If the fourth 
20f60 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67  parameter is neg
20f70 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74  ative, the lengt
20f80 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
20f90 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
20fa0 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
20fb0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
20fc0 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
20fd0 20 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   The fifth argum
20fe0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
20ff0 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  ind_blob(), sqli
21000 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c  te3_bind_text(),
21010 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
21020 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73  bind_text16() is
21030 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
21040 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
21050 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
21060 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
21070 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
21080 20 77 69 74 68 20 69 74 2e 20 49 66 20 74 68 65   with it. If the
21090 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
210a0 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
210b0 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
210c0 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
210d0 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
210e0 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
210f0 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
21100 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
21110 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
21120 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
21130 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 66 74  ..** If the fift
21140 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
21150 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
21160 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
21170 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
21180 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
21190 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
211a0 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
211b0 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
211c0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
211d0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
211e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
211f0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
21200 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
21210 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
21220 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   N that.** is fi
21230 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73  lled with zeroes
21240 2e 20 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73  .  A zeroblob us
21250 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
21260 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
21270 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
21280 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
21290 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
212a0 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
212b0 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
212c0 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
212d0 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
212e0 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
212f0 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
21300 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
21310 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
21320 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
21330 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
21340 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 41  ] routines..** A
21350 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
21360 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
21370 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
21380 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
21390 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
213a0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
213b0 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
213c0 65 64 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c  ed after.** [sql
213d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
213e0 29 5d 20 28 61 6e 64 20 69 74 73 20 76 61 72 69  )] (and its vari
213f0 61 6e 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65  ants) or [sqlite
21400 33 5f 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a  3_reset()] and.*
21410 2a 20 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65  * before [sqlite
21420 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69  3_step()]..** Bi
21430 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
21440 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
21450 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
21460 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f  routine..** Unbo
21470 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
21480 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
21490 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
214a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
214b0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
214c0 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
214d0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a   error code if.*
214e0 2a 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  * anything goes 
214f0 77 72 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f  wrong.  [SQLITE_
21500 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
21510 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
21520 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
21530 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b  out of range.  [
21540 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
21550 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
21560 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20  loc() fails..** 
21570 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
21580 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
21590 64 20 69 66 20 74 68 65 73 65 20 72 6f 75 74 69  d if these routi
215a0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f  nes are called o
215b0 6e 20 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d  n a.** virtual m
215c0 61 63 68 69 6e 65 20 74 68 61 74 20 69 73 20 74  achine that is t
215d0 68 65 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f  he wrong state o
215e0 72 20 77 68 69 63 68 20 68 61 73 20 61 6c 72 65  r which has alre
215f0 61 64 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  ady been finaliz
21600 65 64 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e  ed..** Detection
21610 20 6f 66 20 6d 69 73 75 73 65 20 69 73 20 75 6e   of misuse is un
21620 72 65 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c 69  reliable.  Appli
21630 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e  cations should n
21640 6f 74 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ot depend.** on 
21650 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 72 65  SQLITE_MISUSE re
21660 74 75 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d  turns.  SQLITE_M
21670 49 53 55 53 45 20 69 73 20 69 6e 74 65 6e 64 65  ISUSE is intende
21680 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 61 0a  d to indicate a.
21690 2a 2a 20 61 20 6c 6f 67 69 63 20 65 72 72 6f 72  ** a logic error
216a0 20 69 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74   in the applicat
216b0 69 6f 6e 2e 20 20 46 75 74 75 72 65 20 76 65 72  ion.  Future ver
216c0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
216d0 6d 69 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72  might.** panic r
216e0 61 74 68 65 72 20 74 68 61 6e 20 72 65 74 75 72  ather than retur
216f0 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
21700 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
21710 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
21720 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
21730 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
21740 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
21750 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
21760 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
21770 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
21780 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
21790 2a 0a 2a 2a 20 7b 48 31 33 35 30 36 7d 20 54 68  *.** {H13506} Th
217a0 65 20 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  e [SQL statement
217b0 20 63 6f 6d 70 69 6c 65 72 5d 20 72 65 63 6f 67   compiler] recog
217c0 6e 69 7a 65 73 20 74 6f 6b 65 6e 73 20 6f 66 20  nizes tokens of 
217d0 74 68 65 20 66 6f 72 6d 73 0a 2a 2a 20 20 20 20  the forms.**    
217e0 20 20 20 20 20 20 22 3f 22 2c 20 22 3f 4e 4e 4e        "?", "?NNN
217f0 22 2c 20 22 24 56 56 56 22 2c 20 22 3a 56 56 56  ", "$VVV", ":VVV
21800 22 2c 20 61 6e 64 20 22 40 56 56 56 22 20 61 73  ", and "@VVV" as
21810 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2c   SQL parameters,
21820 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65  .**          whe
21830 72 65 20 4e 4e 4e 20 69 73 20 61 6e 79 20 73 65  re NNN is any se
21840 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72  quence of one or
21850 20 6d 6f 72 65 20 64 69 67 69 74 73 0a 2a 2a 20   more digits.** 
21860 20 20 20 20 20 20 20 20 20 61 6e 64 20 77 68 65           and whe
21870 72 65 20 56 56 56 20 69 73 20 61 6e 79 20 73 65  re VVV is any se
21880 71 75 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72  quence of one or
21890 20 6d 6f 72 65 20 61 6c 70 68 61 6e 75 6d 65 72   more alphanumer
218a0 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  ic.**          c
218b0 68 61 72 61 63 74 65 72 73 20 6f 72 20 22 3a 3a  haracters or "::
218c0 22 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c  " optionally fol
218d0 6c 6f 77 65 64 20 62 79 20 61 20 73 74 72 69 6e  lowed by a strin
218e0 67 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20  g containing.** 
218f0 20 20 20 20 20 20 20 20 20 6e 6f 20 73 70 61 63           no spac
21900 65 73 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65 64  es and contained
21910 20 77 69 74 68 69 6e 20 70 61 72 65 6e 74 68 65   within parenthe
21920 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  ses..**.** {H135
21930 30 39 7d 20 54 68 65 20 69 6e 69 74 69 61 6c 20  09} The initial 
21940 76 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20  value of an SQL 
21950 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
21960 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 32  L..**.** {H13512
21970 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61  } The index of a
21980 6e 20 22 3f 22 20 53 51 4c 20 70 61 72 61 6d 65  n "?" SQL parame
21990 74 65 72 20 69 73 20 6f 6e 65 20 6c 61 72 67 65  ter is one large
219a0 72 20 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20 20  r than the.**   
219b0 20 20 20 20 20 20 20 6c 61 72 67 65 73 74 20 69         largest i
219c0 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61  ndex of SQL para
219d0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 6c 65 66  meter to the lef
219e0 74 2c 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20 20  t, or 1 if.**   
219f0 20 20 20 20 20 20 20 74 68 65 20 22 3f 22 20 69         the "?" i
21a00 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 53  s the leftmost S
21a10 51 4c 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  QL parameter..**
21a20 0a 2a 2a 20 7b 48 31 33 35 31 35 7d 20 54 68 65  .** {H13515} The
21a30 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 4e   index of an "?N
21a40 4e 4e 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65  NN" SQL paramete
21a50 72 20 69 73 20 74 68 65 20 69 6e 74 65 67 65 72  r is the integer
21a60 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33   NNN..**.** {H13
21a70 35 31 38 7d 20 54 68 65 20 69 6e 64 65 78 20 6f  518} The index o
21a80 66 20 61 6e 20 22 3a 56 56 56 22 2c 20 22 24 56  f an ":VVV", "$V
21a90 56 56 22 2c 20 6f 72 20 22 40 56 56 56 22 20 53  VV", or "@VVV" S
21aa0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  QL parameter is.
21ab0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
21ac0 73 61 6d 65 20 61 73 20 74 68 65 20 69 6e 64 65  same as the inde
21ad0 78 20 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f 63  x of leftmost oc
21ae0 63 75 72 72 65 6e 63 65 73 20 6f 66 20 74 68 65  currences of the
21af0 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   same.**        
21b00 20 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20    parameter, or 
21b10 6f 6e 65 20 6d 6f 72 65 20 74 68 61 6e 20 74 68  one more than th
21b20 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20  e largest index 
21b30 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 20  over all.**     
21b40 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 73 20       parameters 
21b50 74 6f 20 74 68 65 20 6c 65 66 74 20 69 66 20 74  to the left if t
21b60 68 69 73 20 69 73 20 74 68 65 20 66 69 72 73 74  his is the first
21b70 20 6f 63 63 75 72 72 65 6e 63 65 0a 2a 2a 20 20   occurrence.**  
21b80 20 20 20 20 20 20 20 20 6f 66 20 74 68 69 73 20          of this 
21b90 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 31 20  parameter, or 1 
21ba0 69 66 20 74 68 69 73 20 69 73 20 74 68 65 20 6c  if this is the l
21bb0 65 66 74 6d 6f 73 74 20 70 61 72 61 6d 65 74 65  eftmost paramete
21bc0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 31  r..**.** {H13521
21bd0 7d 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65  } The [SQL state
21be0 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66  ment compiler] f
21bf0 61 69 6c 73 20 77 69 74 68 20 61 6e 20 5b 53 51  ails with an [SQ
21c00 4c 49 54 45 5f 52 41 4e 47 45 5d 0a 2a 2a 20 20  LITE_RANGE].**  
21c10 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 69 66          error if
21c20 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
21c30 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
21c40 73 20 6c 65 73 73 20 74 68 61 6e 20 31 0a 2a 2a  s less than 1.**
21c50 20 20 20 20 20 20 20 20 20 20 6f 72 20 67 72 65            or gre
21c60 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 63 6f  ater than the co
21c70 6d 70 69 6c 65 2d 74 69 6d 65 20 53 51 4c 49 54  mpile-time SQLIT
21c80 45 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e  E_MAX_VARIABLE_N
21c90 55 4d 42 45 52 0a 2a 2a 20 20 20 20 20 20 20 20  UMBER.**        
21ca0 20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a    parameter..**.
21cb0 2a 2a 20 7b 48 31 33 35 32 34 7d 20 43 61 6c 6c  ** {H13524} Call
21cc0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
21cd0 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
21ce0 33 5f 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e  3_bind(S,N,V,...
21cf0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  )].**          a
21d00 73 73 6f 63 69 61 74 65 20 74 68 65 20 76 61 6c  ssociate the val
21d10 75 65 20 56 20 77 69 74 68 20 61 6c 6c 20 53 51  ue V with all SQ
21d20 4c 20 70 61 72 61 6d 65 74 65 72 73 20 68 61 76  L parameters hav
21d30 69 6e 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20  ing an.**       
21d40 20 20 20 69 6e 64 65 78 20 6f 66 20 4e 20 69 6e     index of N in
21d50 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
21d60 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
21d70 2a 2a 20 7b 48 31 33 35 32 37 7d 20 43 61 6c 6c  ** {H13527} Call
21d80 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
21d90 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65  nd_text | sqlite
21da0 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d  3_bind(S,N,...)]
21db0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65  .**          ove
21dc0 72 72 69 64 65 20 70 72 69 6f 72 20 63 61 6c 6c  rride prior call
21dd0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
21de0 76 61 6c 75 65 73 20 6f 66 20 53 20 61 6e 64 20  values of S and 
21df0 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 30  N..**.** {H13530
21e00 7d 20 42 69 6e 64 69 6e 67 73 20 65 73 74 61 62  } Bindings estab
21e10 6c 69 73 68 65 64 20 62 79 20 5b 73 71 6c 69 74  lished by [sqlit
21e20 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73  e3_bind_text | s
21e30 71 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e 2e  qlite3_bind(S,..
21e40 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
21e50 70 65 72 73 69 73 74 20 61 63 72 6f 73 73 20 63  persist across c
21e60 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
21e70 5f 72 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a  _reset(S)]..**.*
21e80 2a 20 7b 48 31 33 35 33 33 7d 20 49 6e 20 63 61  * {H13533} In ca
21e90 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
21ea0 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
21eb0 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
21ec0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
21ed0 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
21ee0 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
21ef0 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
21f00 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
21f10 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20  )] SQLite binds 
21f20 74 68 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20 20  the first L.**  
21f30 20 20 20 20 20 20 20 20 62 79 74 65 73 20 6f 66          bytes of
21f40 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
21f50 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
21f60 79 20 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 20  y V, when L.**  
21f70 20 20 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 6e          is non-n
21f80 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
21f90 48 31 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c 73  H13536} In calls
21fa0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
21fb0 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
21fc0 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
21fd0 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
21fe0 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
21ff0 29 5d 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20  )] SQLite binds 
22000 63 68 61 72 61 63 74 65 72 73 0a 2a 2a 20 20 20  characters.**   
22010 20 20 20 20 20 20 20 66 72 6f 6d 20 56 20 74 68         from V th
22020 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
22030 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 20 77  zero character w
22040 68 65 6e 20 4c 20 69 73 20 6e 65 67 61 74 69 76  hen L is negativ
22050 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 39  e..**.** {H13539
22060 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
22070 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
22080 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a  (S,N,V,L,D)],.**
22090 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
220a0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e  e3_bind_text(S,N
220b0 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20  ,V,L,D)], or.** 
220c0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
220d0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c  3_bind_text16(S,
220e0 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44  N,V,L,D)] when D
220f0 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a   is the special.
22100 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73  **          cons
22110 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41  tant [SQLITE_STA
22120 54 49 43 5d 2c 20 53 51 4c 69 74 65 20 61 73 73  TIC], SQLite ass
22130 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 76 61  umes that the va
22140 6c 75 65 20 56 0a 2a 2a 20 20 20 20 20 20 20 20  lue V.**        
22150 20 20 69 73 20 68 65 6c 64 20 69 6e 20 73 74 61    is held in sta
22160 74 69 63 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  tic unmanaged sp
22170 61 63 65 20 74 68 61 74 20 77 69 6c 6c 20 6e 6f  ace that will no
22180 74 20 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20 20  t change.**     
22190 20 20 20 20 20 64 75 72 69 6e 67 20 74 68 65 20       during the 
221a0 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20  lifetime of the 
221b0 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b  binding..**.** {
221c0 48 31 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c 73  H13542} In calls
221d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
221e0 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44  d_blob(S,N,V,L,D
221f0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
22200 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
22210 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20  xt(S,N,V,L,D)], 
22220 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  or.**          [
22230 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
22240 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20  t16(S,N,V,L,D)] 
22250 77 68 65 6e 20 44 20 69 73 20 74 68 65 20 73 70  when D is the sp
22260 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20  ecial.**        
22270 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49    constant [SQLI
22280 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
22290 68 65 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73  he routine makes
222a0 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70   a.**          p
222b0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
222c0 68 65 20 76 61 6c 75 65 20 56 20 62 65 66 6f 72  he value V befor
222d0 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
222e0 0a 2a 2a 20 7b 48 31 33 35 34 35 7d 20 49 6e 20  .** {H13545} In 
222f0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
22300 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c  3_bind_blob(S,N,
22310 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,L,D)],.**     
22320 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69       [sqlite3_bi
22330 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c  nd_text(S,N,V,L,
22340 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20  D)], or.**      
22350 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
22360 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c  d_text16(S,N,V,L
22370 2c 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 61  ,D)] when D is a
22380 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20   pointer to.**  
22390 20 20 20 20 20 20 20 20 61 20 66 75 6e 63 74 69          a functi
223a0 6f 6e 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  on, SQLite invok
223b0 65 73 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e  es that function
223c0 20 74 6f 20 64 65 73 74 72 6f 79 20 74 68 65 0a   to destroy the.
223d0 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
223e0 65 20 56 20 61 66 74 65 72 20 69 74 20 68 61 73  e V after it has
223f0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
22400 74 68 65 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a  the value V..**.
22410 2a 2a 20 7b 48 31 33 35 34 38 7d 20 49 6e 20 63  ** {H13548} In c
22420 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
22430 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53  _bind_zeroblob(S
22440 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c  ,N,V,L)] the val
22450 75 65 20 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20  ue bound.**     
22460 20 20 20 20 20 69 73 20 61 20 42 4c 4f 42 20 6f       is a BLOB o
22470 66 20 4c 20 62 79 74 65 73 2c 20 6f 72 20 61 20  f L bytes, or a 
22480 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
22490 20 69 66 20 4c 20 69 73 20 6e 65 67 61 74 69 76   if L is negativ
224a0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 35 31  e..**.** {H13551
224b0 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73  } In calls to [s
224c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
224d0 65 28 53 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20  e(S,N,V)] the V 
224e0 61 72 67 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20  argument may.** 
224f0 20 20 20 20 20 20 20 20 20 62 65 20 65 69 74 68           be eith
22500 65 72 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20  er a [protected 
22510 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
22520 62 6a 65 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 20  bject or an.**  
22530 20 20 20 20 20 20 20 20 5b 75 6e 70 72 6f 74 65          [unprote
22540 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
22550 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69  ue] object..*/.i
22560 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
22570 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
22580 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
22590 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
225a0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
225b0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
225c0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
225d0 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
225e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
225f0 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
22600 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
22610 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
22620 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
22630 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
22640 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
22650 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
22660 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
22670 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
22680 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
22690 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
226a0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
226b0 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
226c0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
226d0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
226e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
226f0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
22700 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
22710 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
22720 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
22730 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
22740 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
22750 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
22760 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
22770 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
22780 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f   int, int n);../
22790 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
227a0 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
227b0 61 6d 65 74 65 72 73 20 7b 48 31 33 36 30 30 7d  ameters {H13600}
227c0 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S70300>.**.** 
227d0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
227e0 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
227f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
22800 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
22810 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
22820 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
22830 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
22840 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
22850 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
22860 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
22870 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
22880 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
22890 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
228a0 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
228b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
228c0 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
228d0 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
228e0 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
228f0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  e..**.** This ro
22900 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
22910 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
22920 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
22930 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
22940 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
22950 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
22960 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
22970 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
22980 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
22990 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
229a0 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
229b0 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20  of the ?NNN are 
229c0 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d  used,.** there m
229d0 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68  ay be gaps in th
229e0 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65  e list..**.** Se
229f0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
22a00 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
22a10 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
22a20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
22a30 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
22a40 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
22a50 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
22a60 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ndex()]..**.** I
22a70 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
22a80 20 7b 48 31 33 36 30 31 7d 20 54 68 65 20 5b 73   {H13601} The [s
22a90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
22aa0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 53 29 5d 20  meter_count(S)] 
22ab0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
22ac0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
22ad0 65 20 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20  e largest index 
22ae0 6f 66 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d  of all SQL param
22af0 65 74 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  eters in the.** 
22b00 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
22b10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c  ed statement] S,
22b20 20 6f 72 20 30 20 69 66 20 53 20 63 6f 6e 74 61   or 0 if S conta
22b30 69 6e 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d  ins no SQL param
22b40 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eters..*/.int sq
22b50 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
22b60 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
22b70 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
22b80 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
22b90 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
22ba0 65 74 65 72 20 7b 48 31 33 36 32 30 7d 20 3c 53  eter {H13620} <S
22bb0 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  70300>.**.** Thi
22bc0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
22bd0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
22be0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e  he name of the n
22bf0 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20 70 61 72 61  -th.** [SQL para
22c00 6d 65 74 65 72 5d 20 69 6e 20 61 20 5b 70 72 65  meter] in a [pre
22c10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22c20 2e 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  ..** SQL paramet
22c30 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
22c40 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
22c50 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
22c60 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
22c70 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
22c80 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
22c90 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
22ca0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
22cb0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
22cc0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
22cd0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
22ce0 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
22cf0 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
22d00 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
22d10 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72  the name..** Par
22d20 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
22d30 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
22d40 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
22d50 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
22d60 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c 73 6f  .** and are also
22d70 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
22d80 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d  "anonymous param
22d90 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  eters"..**.** Th
22da0 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
22db0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
22dc0 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
22dd0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61  .**.** If the va
22de0 6c 75 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20  lue n is out of 
22df0 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
22e00 6e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  n-th parameter i
22e10 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
22e20 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
22e30 72 6e 65 64 2e 20 20 54 68 65 20 72 65 74 75 72  rned.  The retur
22e40 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
22e50 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
22e60 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
22e70 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
22e80 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
22e90 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
22ea0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
22eb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
22ec0 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  6()] or.** [sqli
22ed0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
22ee0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
22ef0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
22f00 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
22f10 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
22f20 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
22f30 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
22f40 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
22f50 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
22f60 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ex()]..**.** INV
22f70 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
22f80 48 31 33 36 32 31 7d 20 54 68 65 20 5b 73 71 6c  H13621} The [sql
22f90 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
22fa0 74 65 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69  ter_name(S,N)] i
22fb0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
22fc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 55  .**          a U
22fd0 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
22fe0 66 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  f the name of th
22ff0 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  e SQL parameter 
23000 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  in.**          t
23010 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
23020 74 65 6d 65 6e 74 5d 20 53 20 68 61 76 69 6e 67  tement] S having
23030 20 69 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a 20   index N, or.** 
23040 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 69 66           NULL if
23050 20 74 68 65 72 65 20 69 73 20 6e 6f 20 53 51 4c   there is no SQL
23060 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68 20   parameter with 
23070 69 6e 64 65 78 20 4e 20 6f 72 20 69 66 20 74 68  index N or if th
23080 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  e.**          pa
23090 72 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64  rameter with ind
230a0 65 78 20 4e 20 69 73 20 61 6e 20 61 6e 6f 6e 79  ex N is an anony
230b0 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 20 22  mous parameter "
230c0 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ?"..*/.const cha
230d0 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
230e0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
230f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23100 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
23110 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
23120 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
23130 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31 33   Given Name {H13
23140 36 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  640} <S70300>.**
23150 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69  .** Return the i
23160 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
23170 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
23180 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a  ts name.  The.**
23190 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
231a0 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
231b0 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
231c0 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
231d0 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
231e0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
231f0 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a  e3_bind()].  A z
23200 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
23210 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
23220 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
23230 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d  ound.  The param
23240 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
23250 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
23260 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
23270 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
23280 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
23290 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
232a0 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
232b0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
232c0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
232d0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
232e0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
232f0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
23300 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
23310 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
23320 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
23330 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
23340 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  x()]..**.** INVA
23350 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
23360 31 33 36 34 31 7d 20 54 68 65 20 5b 73 71 6c 69  13641} The [sqli
23370 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
23380 65 72 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20 69  er_index(S,N)] i
23390 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
233a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
233b0 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61   index of SQL pa
233c0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 5b  rameter in the [
233d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
233e0 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  nt].**          
233f0 53 20 77 68 6f 73 65 20 6e 61 6d 65 20 6d 61 74  S whose name mat
23400 63 68 65 73 20 74 68 65 20 55 54 46 2d 38 20 73  ches the UTF-8 s
23410 74 72 69 6e 67 20 4e 2c 20 6f 72 20 30 20 69 66  tring N, or 0 if
23420 20 74 68 65 72 65 20 69 73 0a 2a 2a 20 20 20 20   there is.**    
23430 20 20 20 20 20 20 6e 6f 20 6d 61 74 63 68 2e 0a        no match..
23440 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
23450 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
23460 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
23470 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
23480 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
23490 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
234a0 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
234b0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
234c0 6e 74 20 7b 48 31 33 36 36 30 7d 20 3c 53 37 30  nt {H13660} <S70
234d0 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72  300>.**.** Contr
234e0 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
234f0 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
23500 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
23510 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
23520 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
23530 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
23540 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
23550 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
23560 2a 2a 20 55 73 65 20 74 68 69 73 20 72 6f 75 74  ** Use this rout
23570 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
23580 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
23590 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
235a0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
235b0 2a 20 7b 48 31 33 36 36 31 7d 20 54 68 65 20 5b  * {H13661} The [
235c0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
235d0 6e 64 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72  ndings(S)] inter
235e0 66 61 63 65 20 72 65 73 65 74 73 20 61 6c 6c 20  face resets all 
235f0 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  SQL.**          
23600 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
23610 67 73 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  gs in the [prepa
23620 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
23630 20 62 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a   back to NULL..*
23640 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
23650 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
23660 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
23670 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
23680 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
23690 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20  In A Result Set 
236a0 7b 48 31 33 37 31 30 7d 20 3c 53 31 30 37 30 30  {H13710} <S10700
236b0 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  >.**.** Return t
236c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
236d0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
236e0 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
236f0 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
23700 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
23710 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
23720 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20  urns 0 if pStmt 
23730 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61  is an SQL.** sta
23740 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
23750 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
23760 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
23770 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a   [UPDATE])..**.*
23780 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
23790 0a 2a 2a 20 7b 48 31 33 37 31 31 7d 20 54 68 65  .** {H13711} The
237a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
237b0 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72  _count(S)] inter
237c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
237d0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20   number of.**   
237e0 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 69         columns i
237f0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
23800 20 67 65 6e 65 72 61 74 65 64 20 62 79 20 74 68   generated by th
23810 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
23820 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20  ement] S,.**    
23830 20 20 20 20 20 20 6f 72 20 30 20 69 66 20 53 20        or 0 if S 
23840 64 6f 65 73 20 6e 6f 74 20 67 65 6e 65 72 61 74  does not generat
23850 65 20 61 20 72 65 73 75 6c 74 20 73 65 74 2e 0a  e a result set..
23860 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
23870 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
23880 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
23890 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
238a0 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
238b0 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 20  In A Result Set 
238c0 7b 48 31 33 37 32 30 7d 20 3c 53 31 30 37 30 30  {H13720} <S10700
238d0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
238e0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
238f0 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
23900 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
23910 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
23920 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
23930 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
23940 65 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ent.  The sqlite
23950 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
23960 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
23970 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
23980 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
23990 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
239a0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
239b0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
239c0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
239d0 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
239e0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
239f0 20 73 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69   string.  The fi
23a00 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
23a10 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
23a20 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
23a30 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
23a40 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
23a50 65 6e 74 2e 20 54 68 65 20 73 65 63 6f 6e 64 20  ent. The second 
23a60 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
23a70 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
23a80 72 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74  r.  The leftmost
23a90 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
23aa0 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72  r 0..**.** The r
23ab0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
23ac0 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
23ad0 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
23ae0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23af0 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
23b00 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
23b10 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
23b20 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
23b30 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
23b40 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
23b50 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
23b60 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
23b70 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
23b80 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33  **.** If sqlite3
23b90 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
23ba0 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
23bb0 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
23bc0 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
23bd0 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
23be0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
23bf0 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
23c00 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
23c10 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
23c20 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
23c30 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
23c40 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
23c50 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
23c60 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
23c70 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
23c80 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
23c90 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
23ca0 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
23cb0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
23cc0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
23cd0 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
23ce0 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
23cf0 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
23d00 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
23d10 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e  e next..**.** IN
23d20 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
23d30 7b 48 31 33 37 32 31 7d 20 41 20 73 75 63 63 65  {H13721} A succe
23d40 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
23d50 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
23d60 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e  _column_name(S,N
23d70 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
23d80 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23d90 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
23da0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65   Nth column (whe
23db0 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20  re 0 is.**      
23dc0 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74      the leftmost
23dd0 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65   column) for the
23de0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
23df0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
23e00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23e10 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d  nt] S as a zero-
23e20 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
23e30 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
23e40 48 31 33 37 32 33 7d 20 41 20 73 75 63 63 65 73  H13723} A succes
23e50 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
23e60 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
23e70 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c  column_name16(S,
23e80 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  N)].**          
23e90 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
23ea0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
23eb0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68  e Nth column (wh
23ec0 65 72 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20  ere 0 is.**     
23ed0 20 20 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73       the leftmos
23ee0 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68  t column) for th
23ef0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
23f00 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
23f10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23f20 65 6e 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f  ent] S as a zero
23f30 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
23f40 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  16 string.**    
23f50 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74        in the nat
23f60 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
23f70 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 34 7d 20 54  **.** {H13724} T
23f80 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
23f90 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 5b  mn_name()] and [
23fa0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
23fb0 61 6d 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20  ame16()].**     
23fc0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20       interfaces 
23fd0 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f  return a NULL po
23fe0 69 6e 74 65 72 20 69 66 20 74 68 65 79 20 61 72  inter if they ar
23ff0 65 20 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 20  e unable to.**  
24000 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65          allocate
24010 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
24020 74 68 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65 74  their normal ret
24030 75 72 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a  urn strings..**.
24040 2a 2a 20 7b 48 31 33 37 32 35 7d 20 49 66 20 74  ** {H13725} If t
24050 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
24060 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
24070 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a  n_name(S,N)] or.
24080 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
24090 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
240a0 31 36 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20  16(S,N)] is out 
240b0 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74  of range, then t
240c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  he.**          i
240d0 6e 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e  nterfaces return
240e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
240f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 36 7d 20  .**.** {H13726} 
24100 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
24110 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
24120 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e  _column_name(S,N
24130 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  )] and.**       
24140 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
24150 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20  mn_name16(S,N)] 
24160 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
24170 74 68 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20 20  the next.**     
24180 20 20 20 20 20 63 61 6c 6c 20 74 6f 20 65 69 74       call to eit
24190 68 65 72 20 72 6f 75 74 69 6e 65 20 77 69 74 68  her routine with
241a0 20 74 68 65 20 73 61 6d 65 20 53 20 61 6e 64 20   the same S and 
241b0 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  N parameters.** 
241c0 20 20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69           or unti
241d0 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  l [sqlite3_final
241e0 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65  ize(S)] is calle
241f0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 37  d..**.** {H13727
24200 7d 20 57 68 65 6e 20 61 20 72 65 73 75 6c 74 20  } When a result 
24210 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45 4c  column of a [SEL
24220 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63  ECT] statement c
24230 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20  ontains.**      
24240 20 20 20 20 61 6e 20 41 53 20 63 6c 61 75 73 65      an AS clause
24250 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  , the name of th
24260 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  at column is the
24270 20 69 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20 20   identifier.**  
24280 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 72          to the r
24290 69 67 68 74 20 6f 66 20 74 68 65 20 41 53 20 6b  ight of the AS k
242a0 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  eyword..*/.const
242b0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
242c0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
242d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
242e0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
242f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
24300 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
24310 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
24320 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
24330 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
24340 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31  Query Result {H1
24350 33 37 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  3740} <S10700>.*
24360 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
24370 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
24380 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
24390 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20   what column of 
243a0 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e  what.** table in
243b0 20 77 68 69 63 68 20 64 61 74 61 62 61 73 65 20   which database 
243c0 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20 5b 53  a result of a [S
243d0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
243e0 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20   comes from..** 
243f0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
24400 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
24410 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
24420 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
24430 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
24440 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
24450 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61 73  g.  The _databas
24460 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
24470 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  rn.** the databa
24480 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61  se name, the _ta
24490 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ble_ routines re
244a0 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e  turn the table n
244b0 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20  ame, and.** the 
244c0 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73  origin_ routines
244d0 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75   return the colu
244e0 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20  mn name..** The 
244f0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
24500 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
24510 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
24520 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
24530 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  oyed.** using [s
24540 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
24550 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
24560 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
24570 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
24580 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
24590 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
245a0 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20  **.** The names 
245b0 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
245c0 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
245d0 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
245e0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
245f0 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
24600 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
24610 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
24620 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c  e following call
24630 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
24640 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
24650 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
24660 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
24670 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
24680 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
24690 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
246a0 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
246b0 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
246c0 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
246d0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20  *.** If the Nth 
246e0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
246f0 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
24700 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
24710 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
24720 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
24730 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
24740 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
24750 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
24760 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72  * NULL.  These r
24770 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
24780 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
24790 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
247a0 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
247b0 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65  curs.  Otherwise
247c0 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
247d0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
247e0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
247f0 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63 6f   table.** and co
24800 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
24810 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
24820 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
24830 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20  ..**.** As with 
24840 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
24850 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73   APIs, those pos
24860 74 66 69 78 65 64 20 77 69 74 68 20 22 31 36 22  tfixed with "16"
24870 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
24880 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
24890 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  s, the other fun
248a0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
248b0 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  F-8. {END}.**.**
248c0 20 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20   These APIs are 
248d0 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
248e0 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
248f0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
24900 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
24910 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
24920 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
24930 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
24940 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 33  ined..**.** {A13
24950 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  751}.** If two o
24960 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
24970 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
24980 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
24990 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
249a0 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
249b0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
249c0 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
249d0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
249e0 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
249f0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  efined..**.** IN
24a00 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
24a10 7b 48 31 33 37 34 31 7d 20 54 68 65 20 5b 73 71  {H13741} The [sq
24a20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
24a30 61 62 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d  abase_name(S,N)]
24a40 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
24a50 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
24a60 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 38 20        the UTF-8 
24a70 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
24a80 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
24a90 62 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20  base from which 
24aa0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
24ab0 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
24ac0 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72  n of the [prepar
24ad0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
24ae0 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a  is extracted,.**
24af0 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c            or NUL
24b00 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  L if the Nth col
24b10 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65  umn of S is a ge
24b20 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
24b30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
24b40 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  if unable to all
24b50 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
24b60 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
24b70 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 32 7d 20 54  **.** {H13742} T
24b80 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
24b90 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
24ba0 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  16(S,N)] interfa
24bb0 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
24bc0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
24bd0 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  e UTF-16 native 
24be0 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d  byte order zero-
24bf0 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20  terminated name 
24c00 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
24c10 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d  **          from
24c20 20 77 68 69 63 68 20 74 68 65 20 4e 74 68 20 72   which the Nth r
24c30 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
24c40 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
24c50 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a  atement] S is.**
24c60 20 20 20 20 20 20 20 20 20 20 65 78 74 72 61 63            extrac
24c70 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20  ted, or NULL if 
24c80 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
24c90 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c  f S is a general
24ca0 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20   expression.**  
24cb0 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e          or if un
24cc0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
24cd0 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65   memory to store
24ce0 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a   the name..**.**
24cf0 20 7b 48 31 33 37 34 33 7d 20 54 68 65 20 5b 73   {H13743} The [s
24d00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
24d10 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69  ble_name(S,N)] i
24d20 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24d30 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
24d40 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65      the UTF-8 ze
24d50 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
24d60 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  me of the table 
24d70 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a  from which the.*
24d80 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 72  *          Nth r
24d90 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  esult column of 
24da0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
24db0 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78  atement] S is ex
24dc0 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20  tracted,.**     
24dd0 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20       or NULL if 
24de0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
24df0 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c  f S is a general
24e00 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20   expression.**  
24e10 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e          or if un
24e20 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
24e30 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65   memory to store
24e40 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a   the name..**.**
24e50 20 7b 48 31 33 37 34 34 7d 20 54 68 65 20 5b 73   {H13744} The [s
24e60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
24e70 62 6c 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d  ble_name16(S,N)]
24e80 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
24e90 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20  ns either.**    
24ea0 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31 36        the UTF-16
24eb0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
24ec0 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  er zero-terminat
24ed0 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74  ed name of the t
24ee0 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  able.**         
24ef0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
24f00 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
24f10 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72  n of the [prepar
24f20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
24f30 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  is.**          e
24f40 78 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c  xtracted, or NUL
24f50 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c  L if the Nth col
24f60 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65  umn of S is a ge
24f70 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e  neral expression
24f80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
24f90 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  if unable to all
24fa0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
24fb0 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a  store the name..
24fc0 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 35 7d 20 54  **.** {H13745} T
24fd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
24fe0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 53  mn_origin_name(S
24ff0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
25000 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
25010 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
25020 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
25030 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
25040 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 6f  table column fro
25050 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20  m which the.**  
25060 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73 75          Nth resu
25070 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  lt column of the
25080 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25090 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61  ment] S is extra
250a0 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20  cted,.**        
250b0 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65    or NULL if the
250c0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53   Nth column of S
250d0 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78   is a general ex
250e0 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20  pression.**     
250f0 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c       or if unabl
25100 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
25110 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68  mory to store th
25120 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  e name..**.** {H
25130 31 33 37 34 36 7d 20 54 68 65 20 5b 73 71 6c 69  13746} The [sqli
25140 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
25150 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69  n_name16(S,N)] i
25160 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
25170 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
25180 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e      the UTF-16 n
25190 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
251a0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
251b0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62   name of the tab
251c0 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  le.**          c
251d0 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68  olumn from which
251e0 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
251f0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
25200 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
25210 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
25220 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f   is extracted, o
25230 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74  r NULL if the Nt
25240 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20  h column.**     
25250 20 20 20 20 20 6f 66 20 53 20 69 73 20 61 20 67       of S is a g
25260 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
25270 6e 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74  n or if unable t
25280 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
25290 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  y.**          to
252a0 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
252b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 38 7d 20  .**.** {H13748} 
252c0 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
252d0 73 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20  s from.**       
252e0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
252f0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
25300 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
25310 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
25320 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20 76  *          are v
25330 61 6c 69 64 20 66 6f 72 20 74 68 65 20 6c 69 66  alid for the lif
25340 65 74 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 72  etime of the [pr
25350 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25360 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ].**          or
25370 20 75 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f 64   until the encod
25380 69 6e 67 20 69 73 20 63 68 61 6e 67 65 64 20 62  ing is changed b
25390 79 20 61 6e 6f 74 68 65 72 20 6d 65 74 61 64 61  y another metada
253a0 74 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ta.**          i
253b0 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 66 6f  nterface call fo
253c0 72 20 74 68 65 20 73 61 6d 65 20 70 72 65 70 61  r the same prepa
253d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
253e0 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
253f0 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
25400 2a 2a 20 7b 41 31 33 37 35 31 7d 20 49 66 20 74  ** {A13751} If t
25410 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
25420 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
25430 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ore.**          
25440 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
25450 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
25460 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
25470 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20  interfaces].**  
25480 20 20 20 20 20 20 20 20 66 6f 72 20 74 68 65 20          for the 
25490 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
254a0 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
254b0 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20  sult column.**  
254c0 20 20 20 20 20 20 20 20 61 74 20 74 68 65 20 73          at the s
254d0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
254e0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
254f0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
25500 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
25510 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
25520 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
25530 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
25540 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
25550 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
25560 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
25570 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
25580 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
25590 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
255a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
255b0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
255c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
255d0 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
255e0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
255f0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
25600 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
25610 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
25620 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
25630 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
25640 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
25650 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
25660 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
25670 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
25680 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
25690 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37  ery Result {H137
256a0 36 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  60} <S10700>.**.
256b0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
256c0 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
256d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
256e0 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
256f0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
25700 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
25710 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
25720 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
25730 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
25740 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
25750 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
25760 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
25770 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
25780 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
25790 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
257a0 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
257b0 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
257c0 20 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c    If the Nth col
257d0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
257e0 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
257f0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
25800 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
25810 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
25820 74 75 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72  turned..** The r
25830 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
25840 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
25850 6e 63 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a  ncoded. {END}.**
25860 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
25870 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
25880 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
25890 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
258a0 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
258b0 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
258c0 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
258d0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
258e0 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
258f0 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
25900 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
25910 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
25920 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
25930 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
25940 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
25950 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
25960 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
25970 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
25980 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
25990 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ==0)..**.** SQLi
259a0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
259b0 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
259c0 20 20 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73    So just becaus
259d0 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
259e0 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
259f0 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
25a00 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
25a10 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
25a20 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
25a30 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
25a40 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
25a50 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
25a60 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
25a70 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
25a80 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
25a90 20 73 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a   static.  Type.*
25aa0 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
25ab0 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
25ac0 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
25ad0 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
25ae0 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
25af0 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a  those values..**
25b00 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
25b10 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 31 7d 20 20  **.** {H13761}  
25b20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
25b30 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
25b40 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c  lumn_decltype(S,
25b50 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a  N)] returns a.**
25b60 20 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d             zero-
25b70 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
25b80 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
25b90 6e 67 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  ng the declared 
25ba0 64 61 74 61 74 79 70 65 0a 2a 2a 20 20 20 20 20  datatype.**     
25bb0 20 20 20 20 20 20 6f 66 20 74 68 65 20 74 61 62        of the tab
25bc0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61  le column that a
25bd0 70 70 65 61 72 73 20 61 73 20 74 68 65 20 4e 74  ppears as the Nt
25be0 68 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72  h column (number
25bf0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ed.**           
25c00 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72  from 0) of the r
25c10 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65  esult set to the
25c20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25c30 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b  ment] S..**.** {
25c40 48 31 33 37 36 32 7d 20 20 41 20 73 75 63 63 65  H13762}  A succe
25c50 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
25c60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
25c70 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a 2a  cltype16(S,N)].*
25c80 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75  *           retu
25c90 72 6e 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69  rns a zero-termi
25ca0 6e 61 74 65 64 20 55 54 46 2d 31 36 20 6e 61 74  nated UTF-16 nat
25cb0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 73  ive byte order s
25cc0 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tring.**        
25cd0 20 20 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68     containing th
25ce0 65 20 64 65 63 6c 61 72 65 64 20 64 61 74 61 74  e declared datat
25cf0 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
25d00 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70   column that app
25d10 65 61 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ears.**         
25d20 20 20 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c    as the Nth col
25d30 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72  umn (numbered fr
25d40 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73  om 0) of the res
25d50 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a  ult set to the.*
25d60 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  *           [pre
25d70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25d80 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36   S..**.** {H1376
25d90 33 7d 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73  3}  If N is less
25da0 20 74 68 61 6e 20 30 20 6f 72 20 4e 20 69 73 20   than 0 or N is 
25db0 67 72 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20  greater than or 
25dc0 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20 20  equal to.**     
25dd0 20 20 20 20 20 20 74 68 65 20 6e 75 6d 62 65 72        the number
25de0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
25df0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
25e00 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20  tement] S,.**   
25e10 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 74 68          or if th
25e20 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
25e30 53 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  S is an expressi
25e40 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 20 72  on or subquery r
25e50 61 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ather.**        
25e60 20 20 20 74 68 61 6e 20 61 20 74 61 62 6c 65 20     than a table 
25e70 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69 66 20 61 20  column, or if a 
25e80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
25e90 6e 20 66 61 69 6c 75 72 65 0a 2a 2a 20 20 20 20  n failure.**    
25ea0 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75         occurs du
25eb0 72 69 6e 67 20 65 6e 63 6f 64 69 6e 67 20 63 6f  ring encoding co
25ec0 6e 76 65 72 73 69 6f 6e 73 2c 20 74 68 65 6e 0a  nversions, then.
25ed0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 63 61 6c  **           cal
25ee0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ls to [sqlite3_c
25ef0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53  olumn_decltype(S
25f00 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  ,N)] or.**      
25f10 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
25f20 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
25f30 53 2c 4e 29 5d 20 72 65 74 75 72 6e 20 4e 55 4c  S,N)] return NUL
25f40 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  L..*/.const char
25f50 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
25f60 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
25f70 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
25f80 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
25f90 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
25fa0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
25fb0 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
25fc0 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
25fd0 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
25fe0 6e 74 20 7b 48 31 33 32 30 30 7d 20 3c 53 31 30  nt {H13200} <S10
25ff0 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  000>.**.** After
26000 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
26010 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
26020 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
26030 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
26040 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
26050 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
26060 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
26070 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
26080 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
26090 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
260a0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
260b0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
260c0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
260d0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
260e0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
260f0 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
26100 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
26110 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
26120 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
26130 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
26140 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
26150 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
26160 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
26170 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
26180 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
26190 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
261a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
261b0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
261c0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
261d0 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
261e0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
261f0 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
26200 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
26210 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
26220 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
26230 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
26240 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
26250 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
26260 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
26270 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
26280 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
26290 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
262a0 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ported..**.** In
262b0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
262c0 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
262d0 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
262e0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
262f0 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
26300 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
26310 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
26320 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
26330 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74  _MISUSE]..** Wit
26340 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
26350 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
26360 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
26370 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
26380 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
26390 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
263a0 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
263b0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  *.** [SQLITE_BUS
263c0 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
263d0 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
263e0 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
263f0 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
26400 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
26410 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
26420 20 6a 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74   job.  If the st
26430 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
26440 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
26450 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
26460 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
26470 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
26480 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
26490 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
264a0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
264b0 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
264c0 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
264d0 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20  n a.** explicit 
264e0 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
264f0 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
26500 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
26510 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
26520 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
26530 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d   [SQLITE_DONE] m
26540 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
26550 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
26560 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
26570 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
26580 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
26590 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
265a0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
265b0 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
265c0 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
265d0 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
265e0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
265f0 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
26600 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
26610 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
26620 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49  l state..**.** I
26630 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
26640 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
26650 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
26660 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
26670 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
26680 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
26690 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
266a0 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
266b0 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
266c0 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
266d0 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
266e0 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
266f0 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
26700 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
26710 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
26720 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
26730 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
26740 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
26750 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  **.** [SQLITE_ER
26760 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
26770 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
26780 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
26790 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
267a0 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
267b0 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
267c0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
267d0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
267e0 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
267f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
26800 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
26810 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
26820 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68  rmsg()]..** With
26830 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
26840 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
26850 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
26860 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
26870 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
26880 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
26890 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
268a0 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
268b0 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
268c0 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
268d0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
268e0 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
268f0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
26900 65 6d 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20  ement].  In the 
26910 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a  "v2" interface,.
26920 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  ** the more spec
26930 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
26940 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  is returned dire
26950 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ctly by sqlite3_
26960 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53  step()..**.** [S
26970 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65  QLITE_MISUSE] me
26980 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69  ans that the thi
26990 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61  s routine was ca
269a0 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61  lled inappropria
269b0 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73  tely..** Perhaps
269c0 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f   it was called o
269d0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
269e0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
269f0 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65  s.** already bee
26a00 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  n [sqlite3_final
26a10 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d  ize | finalized]
26a20 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20   or on one that 
26a30 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  had.** previousl
26a40 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  y returned [SQLI
26a50 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51  TE_ERROR] or [SQ
26a60 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20  LITE_DONE].  Or 
26a70 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74  it could.** be t
26a80 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
26a90 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
26aa0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69  onnection is bei
26ab0 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f  ng used by two o
26ac0 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64  r.** more thread
26ad0 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f  s at the same mo
26ae0 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a  ment in time..**
26af0 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
26b00 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
26b10 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
26b20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
26b30 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
26b40 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
26b50 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
26b60 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
26b70 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
26b80 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
26b90 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
26ba0 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
26bb0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
26bc0 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
26bd0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
26be0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
26bf0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
26c00 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
26c10 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
26c20 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
26c30 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
26c40 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
26c50 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
26c60 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
26c70 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
26c80 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
26c90 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
26ca0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
26cb0 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
26cc0 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
26cd0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
26ce0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
26cf0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
26d00 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
26d10 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
26d20 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
26d30 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
26d40 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
26d50 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
26d60 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
26d70 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
26d80 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
26d90 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
26da0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
26db0 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
26dc0 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
26dd0 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
26de0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
26df0 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ended..**.** INV
26e00 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
26e10 48 31 33 32 30 32 7d 20 20 49 66 20 74 68 65 20  H13202}  If the 
26e20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26e30 65 6e 74 5d 20 53 20 69 73 20 72 65 61 64 79 20  ent] S is ready 
26e40 74 6f 20 62 65 20 72 75 6e 2c 20 74 68 65 6e 0a  to be run, then.
26e50 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71  **           [sq
26e60 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 61  lite3_step(S)] a
26e70 64 76 61 6e 63 65 73 20 74 68 61 74 20 70 72 65  dvances that pre
26e80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
26e90 75 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20  until.**        
26ea0 20 20 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72     completion or
26eb0 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65 61   until it is rea
26ec0 64 79 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f  dy to return ano
26ed0 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65 0a  ther row of the.
26ee0 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 73  **           res
26ef0 75 6c 74 20 73 65 74 2c 20 6f 72 20 75 6e 74 69  ult set, or unti
26f00 6c 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e  l an [sqlite3_in
26f10 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72  terrupt | interr
26f20 75 70 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  upt].**         
26f30 20 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20    or a run-time 
26f40 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
26f50 0a 2a 2a 20 7b 48 31 35 33 30 34 7d 20 20 57 68  .** {H15304}  Wh
26f60 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  en a call to [sq
26f70 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63  lite3_step(S)] c
26f80 61 75 73 65 73 20 74 68 65 20 5b 70 72 65 70 61  auses the [prepa
26f90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
26fa0 2a 20 20 20 20 20 20 20 20 20 20 20 53 20 74 6f  *           S to
26fb0 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69   run to completi
26fc0 6f 6e 2c 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  on, the function
26fd0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
26fe0 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  _DONE]..**.** {H
26ff0 31 35 33 30 36 7d 20 20 57 68 65 6e 20 61 20 63  15306}  When a c
27000 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
27010 73 74 65 70 28 53 29 5d 20 73 74 6f 70 73 20 62  step(S)] stops b
27020 65 63 61 75 73 65 20 69 74 20 69 73 20 72 65 61  ecause it is rea
27030 64 79 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  dy to.**        
27040 20 20 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65     return anothe
27050 72 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  r row of the res
27060 75 6c 74 20 73 65 74 2c 20 69 74 20 72 65 74 75  ult set, it retu
27070 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  rns [SQLITE_ROW]
27080 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 38 7d  ..**.** {H15308}
27090 20 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b    If a call to [
270a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
270b0 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e 0a 2a   encounters an.*
270c0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
270d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c  ite3_interrupt |
270e0 20 69 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61   interrupt] or a
270f0 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 2c   run-time error,
27100 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74  .**           it
27110 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
27120 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 63 6f  opriate error co
27130 64 65 20 74 68 61 74 20 69 73 20 6e 6f 74 20 6f  de that is not o
27140 6e 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  ne of.**        
27150 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20     [SQLITE_OK], 
27160 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 6f 72  [SQLITE_ROW], or
27170 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a   [SQLITE_DONE]..
27180 2a 2a 0a 2a 2a 20 7b 48 31 35 33 31 30 7d 20 20  **.** {H15310}  
27190 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  If an [sqlite3_i
271a0 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72  nterrupt | inter
271b0 72 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74  rupt] or a run-t
271c0 69 6d 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20  ime error.**    
271d0 20 20 20 20 20 20 20 6f 63 63 75 72 73 20 64 75         occurs du
271e0 72 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b  ring a call to [
271f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
27200 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f  .**           fo
27210 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
27220 61 74 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74  atement] S creat
27230 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
27240 20 20 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74        legacy int
27250 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
27260 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a  _prepare()] or.*
27270 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  *           [sql
27280 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
27290 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63  ], then the func
272a0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 74  tion returns eit
272b0 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
272c0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
272d0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20   [SQLITE_BUSY], 
272e0 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
272f0 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  E]..*/.int sqlit
27300 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
27310 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
27320 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
27330 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
27340 72 65 73 75 6c 74 20 73 65 74 20 7b 48 31 33 37  result set {H137
27350 37 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  70} <S10700>.**.
27360 2a 2a 20 52 65 74 75 72 6e 73 20 74 68 65 20 6e  ** Returns the n
27370 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20  umber of values 
27380 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
27390 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
273a0 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   set..**.** INVA
273b0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
273c0 31 33 37 37 31 7d 20 20 41 66 74 65 72 20 61 20  13771}  After a 
273d0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
273e0 5f 73 74 65 70 28 53 29 5d 20 74 68 61 74 20 72  _step(S)] that r
273f0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52  eturns [SQLITE_R
27400 4f 57 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  OW],.**         
27410 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64    the [sqlite3_d
27420 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f  ata_count(S)] ro
27430 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72  utine will retur
27440 6e 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  n the same value
27450 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 73  .**           as
27460 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
27470 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 66  lumn_count(S)] f
27480 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b  unction..**.** {
27490 48 31 33 37 37 32 7d 20 20 41 66 74 65 72 20 5b  H13772}  After [
274a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
274b0 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e   has returned an
274c0 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
274d0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  an.**           
274e0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
274f0 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f  before [sqlite3_
27500 73 74 65 70 28 53 29 5d 20 68 61 73 20 62 65 65  step(S)] has bee
27510 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 0a  n called on the.
27520 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 70 72  **           [pr
27530 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27540 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
27550 74 69 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61  time since it wa
27560 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  s.**           [
27570 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
27580 7c 20 70 72 65 70 61 72 65 64 5d 20 6f 72 20 5b  | prepared] or [
27590 73 71 6c 69 74 65 33 5f 72 65 73 65 74 20 7c 20  sqlite3_reset | 
275a0 72 65 73 65 74 5d 2c 0a 2a 2a 20 20 20 20 20 20  reset],.**      
275b0 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
275c0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d  3_data_count(S)]
275d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
275e0 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71   zero..*/.int sq
275f0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
27600 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
27610 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
27620 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
27630 74 61 6c 20 44 61 74 61 74 79 70 65 73 20 7b 48  tal Datatypes {H
27640 31 30 32 36 35 7d 20 3c 53 31 30 31 31 30 3e 3c  10265} <S10110><
27650 53 31 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S10120>.** KEYWO
27660 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
27670 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d 20  .**.** {H10266} 
27680 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53  Every value in S
27690 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66  QLite has one of
276a0 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61   five fundamenta
276b0 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a  l datatypes:.**.
276c0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
276d0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
276e0 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34  teger.** <li> 64
276f0 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69  -bit IEEE floati
27700 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a  ng point number.
27710 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a  ** <li> string.*
27720 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c  * <li> BLOB.** <
27730 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c  li> NULL.** </ul
27740 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  > {END}.**.** Th
27750 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
27760 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
27770 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
27780 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
27790 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
277a0 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
277b0 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
277c0 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
277d0 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
277e0 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
277f0 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
27800 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
27810 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
27820 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
27830 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
27840 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
27850 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
27860 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
27870 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
27880 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
27890 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
278a0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
278b0 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
278c0 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
278d0 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
278e0 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
278f0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
27900 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
27910 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
27920 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
27930 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
27940 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27950 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
27960 72 6f 6d 20 41 20 51 75 65 72 79 20 7b 48 31 33  rom A Query {H13
27970 38 30 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a  800} <S10700>.**
27980 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
27990 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
279a0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ons}.**.** These
279b0 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74   routines form t
279c0 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 20 71  he "result set q
279d0 75 65 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e  uery" interface.
279e0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
279f0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
27a00 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
27a10 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
27a20 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
27a30 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
27a40 20 71 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72   query.  In ever
27a50 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
27a60 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
27a70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
27a80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27a90 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
27aa0 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
27ab0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
27ac0 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
27ad0 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
27ae0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
27af0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
27b00 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
27b10 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
27b20 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
27b30 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
27b40 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
27b50 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
27b60 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20  d be returned.  
27b70 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
27b80 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
27b90 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
27ba0 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  dex 0..**.** If 
27bb0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
27bc0 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65  t does not curre
27bd0 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20  ntly point to a 
27be0 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66  valid row, or if
27bf0 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69   the.** column i
27c00 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
27c10 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
27c20 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
27c30 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
27c40 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
27c50 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
27c60 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
27c70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
27c80 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
27c90 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
27ca0 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
27cb0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
27cc0 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
27cd0 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65  alize()] have be
27ce0 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71  en called subseq
27cf0 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
27d00 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
27d10 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
27d20 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
27d30 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
27d40 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
27d50 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
27d60 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
27d70 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
27d80 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
27d90 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
27da0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
27db0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
27dc0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
27dd0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
27de0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
27df0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
27e00 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
27e10 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
27e20 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
27e30 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
27e40 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
27e50 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
27e60 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
27e70 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
27e80 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
27e90 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
27ea0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
27eb0 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
27ec0 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
27ed0 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
27ee0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
27ef0 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20  lt column.  The 
27f00 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
27f10 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
27f20 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
27f30 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
27f40 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
27f50 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
27f60 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
27f70 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
27f80 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
27f90 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
27fa0 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
27fb0 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
27fc0 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
27fd0 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
27fe0 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
27ff0 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
28000 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
28010 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
28020 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
28030 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
28040 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
28050 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
28060 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
28070 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
28080 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
28090 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
280a0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
280b0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  n..**.** If the 
280c0 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
280d0 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
280e0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
280f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
28100 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
28110 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
28120 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
28130 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
28140 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
28150 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
28160 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
28170 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
28180 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
28190 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
281a0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
281b0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
281c0 62 79 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65  bytes..** If the
281d0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
281e0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
281f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
28200 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
28210 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
28220 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
28230 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
28240 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
28250 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
28260 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
28270 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
28280 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75  * The value retu
28290 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e  rned does not in
282a0 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
282b0 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65  erminator at the
282c0 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
282d0 74 72 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72  tring.  For clar
282e0 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72  ity: the value r
282f0 65 74 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e  eturned is the n
28300 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
28310 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
28320 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
28330 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
28340 2a 0a 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74  *.** Strings ret
28350 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
28360 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
28370 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
28380 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
28390 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
283a0 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
283b0 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro terminated.  
283c0 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
283d0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
283e0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
283f0 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
28400 20 42 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69   BLOB is an arbi
28410 74 72 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72  trary.** pointer
28420 2c 20 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20  , possibly even 
28430 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
28440 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
28450 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
28460 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
28470 6d 69 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33  milar to sqlite3
28480 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
28490 2a 2a 20 62 75 74 20 6c 65 61 76 65 73 20 74 68  ** but leaves th
284a0 65 20 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d  e result in UTF-
284b0 31 36 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  16 in native byt
284c0 65 20 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20  e order instead 
284d0 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65  of UTF-8..** The
284e0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
284f0 20 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64   is not included
28500 20 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a   in this count..
28510 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74  **.** The object
28520 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
28530 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
28540 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
28550 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
28560 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
28570 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74  t.  An unprotect
28580 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
28590 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f   object.** may o
285a0 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
285b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
285c0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
285d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
285e0 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
285f0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
28600 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
28610 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
28620 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
28630 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
28640 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
28650 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
28660 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
28670 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
28680 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
28690 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
286a0 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
286b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
286c0 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  es()], then the 
286d0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
286e0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
286f0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
28700 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
28710 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
28720 70 70 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72  ppropriate.  For
28730 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
28740 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
28750 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
28760 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
28770 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
28780 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
28790 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
287a0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
287b0 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
287c0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
287d0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65  omatically.  The
287e0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
287f0 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
28800 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
28810 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
28820 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
28830 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
28840 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
28850 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
28860 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
28870 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
28880 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
28890 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
288a0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
288b0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
288c0 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
288d0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
288e0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
288f0 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
28900 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
28910 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
28920 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
28930 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
28940 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
28950 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
28960 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55  td> Result is NU
28970 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
28980 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
28990 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
289a0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
289b0 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
289c0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
289d0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
289e0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
289f0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
28a00 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
28a10 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
28a20 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
28a30 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
28a40 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
28a50 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
28a60 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
28a70 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66  > Convert from f
28a80 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a  loat to integer.
28a90 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
28aa0 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  AT   <td>   TEXT
28ab0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
28ac0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
28ad0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
28ae0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
28af0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
28b00 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45  ame as FLOAT->TE
28b10 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
28b20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54  TEXT    <td> INT
28b30 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20  EGER   <td> Use 
28b40 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
28b50 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
28b60 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
28b70 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  Use atof().** <t
28b80 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
28b90 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
28ba0 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
28bb0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
28bc0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
28bd0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74    <td> Convert t
28be0 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20  o TEXT then use 
28bf0 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atoi().** <tr><t
28c00 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
28c10 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
28c20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
28c30 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a  then use atof().
28c40 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
28c50 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
28c60 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
28c70 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
28c80 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
28c90 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
28ca0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
28cb0 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65  table above make
28cc0 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73  s reference to s
28cd0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
28ce0 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69  y functions atoi
28cf0 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29  ().** and atof()
28d00 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e  .  SQLite does n
28d10 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68  ot really use th
28d20 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
28d30 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77  It has its.** ow
28d40 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74  n equivalent int
28d50 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20  ernal routines. 
28d60 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20   The atoi() and 
28d70 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65  atof() names are
28d80 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20  .** used in the 
28d90 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74  table for brevit
28da0 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68  y and because th
28db0 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20  ey are familiar 
28dc0 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f  to most.** C pro
28dd0 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  grammers..**.** 
28de0 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
28df0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
28e00 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
28e10 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
28e20 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
28e30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
28e40 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
28e50 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
28e60 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
28e70 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
28e80 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
28e90 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72  ..** Type conver
28ea0 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
28eb0 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
28ec0 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
28ed0 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
28ee0 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
28ef0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
28f00 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
28f10 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
28f20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
28f30 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
28f40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
28f50 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
28f60 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
28f70 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
28f80 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
28f90 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
28fa0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
28fb0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
28fc0 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
28fd0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
28fe0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
28ff0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
29000 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
29010 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
29020 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
29030 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
29040 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69    to UTF-16.</li
29050 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
29060 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
29070 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
29080 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29090 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
290a0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
290b0 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
290c0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
290d0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
290e0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
290f0 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  F-8.</li>.** </u
29100 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73  l>.**.** Convers
29110 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
29120 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
29130 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
29140 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
29150 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
29160 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
29170 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
29180 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
29190 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
291a0 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
291b0 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74  or pointer point
291c0 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62  s to will have b
291d0 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
291e0 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
291f0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
29200 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
29210 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
29220 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
29230 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
29240 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
29250 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
29260 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
29270 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
29280 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
29290 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
292a0 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
292b0 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
292c0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
292d0 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
292e0 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
292f0 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
29300 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29310 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
29320 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
29330 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
29340 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
29350 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
29360 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
29370 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
29380 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
29390 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
293a0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
293b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
293c0 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
293d0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
293e0 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
293f0 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
29400 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
29410 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
29420 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
29430 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
29440 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
29450 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
29460 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
29470 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
29480 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
29490 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
294a0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
294b0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
294c0 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
294d0 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
294e0 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
294f0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
29500 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
29510 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
29520 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
29530 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
29540 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
29550 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
29560 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
29570 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
29580 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
29590 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
295a0 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  bytes()..**.** T
295b0 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
295c0 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
295d0 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
295e0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
295f0 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
29600 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
29610 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
29620 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
29630 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
29640 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
29650 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d  s called.  The m
29660 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
29670 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
29680 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
29690 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
296a0 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
296b0 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
296c0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
296d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
296e0 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
296f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29700 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
29710 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
29720 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d  )]..**.** If a m
29730 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
29740 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
29750 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74  ring the evaluat
29760 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ion of any.** of
29770 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c   these routines,
29780 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65   a default value
29790 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
297a0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
297b0 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68  .** is either th
297c0 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65  e integer 0, the
297d0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
297e0 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61  number 0.0, or a
297f0 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
29800 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61  .  Subsequent ca
29810 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
29820 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20  errcode()] will 
29830 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
29840 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
29850 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
29860 2a 20 7b 48 31 33 38 30 33 7d 20 54 68 65 20 5b  * {H13803} The [
29870 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29880 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  lob(S,N)] interf
29890 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
298a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68  .**          Nth
298b0 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
298c0 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
298d0 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72  e result set for
298e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
298f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29900 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 42  ment] S into a B
29910 4c 4f 42 20 61 6e 64 20 74 68 65 6e 20 72 65 74  LOB and then ret
29920 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  urns a.**       
29930 20 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68     pointer to th
29940 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75  e converted valu
29950 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 36  e..**.** {H13806
29960 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
29970 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29  olumn_bytes(S,N)
29980 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
29990 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rns the.**      
299a0 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79      number of by
299b0 74 65 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 20  tes in the BLOB 
299c0 6f 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75  or string (exclu
299d0 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20  sive of the.**  
299e0 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72          zero ter
299f0 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73  minator on the s
29a00 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20  tring) that was 
29a10 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
29a20 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74  **          most
29a30 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
29a40 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
29a50 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a  blob(S,N)] or.**
29a60 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
29a70 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53  e3_column_text(S
29a80 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ,N)]..**.** {H13
29a90 38 30 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  809} The [sqlite
29aa0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
29ab0 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
29ac0 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
29ad0 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
29ae0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
29af0 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76  string (exclusiv
29b00 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  e of the.**     
29b10 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e       zero termin
29b20 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69  ator on the stri
29b30 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74  ng) that was ret
29b40 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
29b50 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65           most re
29b60 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
29b70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
29b80 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a  t16(S,N)]..**.**
29b90 20 7b 48 31 33 38 31 32 7d 20 54 68 65 20 5b 73   {H13812} The [s
29ba0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
29bb0 75 62 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  uble(S,N)] inter
29bc0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
29bd0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
29be0 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
29bf0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
29c00 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
29c10 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
29c20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
29c30 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
29c40 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
29c50 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20  alue and.**     
29c60 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63       returns a c
29c70 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75  opy of that valu
29c80 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 35  e..**.** {H13815
29c90 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
29ca0 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20  olumn_int(S,N)] 
29cb0 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
29cc0 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
29cd0 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
29ce0 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
29cf0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
29d00 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  et for the.**   
29d10 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
29d20 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
29d30 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e  to a 64-bit sign
29d40 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a  ed integer and.*
29d50 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
29d60 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20  ns the lower 32 
29d70 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74  bits of that int
29d80 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  eger..**.** {H13
29d90 38 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  818} The [sqlite
29da0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 53  3_column_int64(S
29db0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,N)] interface c
29dc0 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
29dd0 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75          Nth colu
29de0 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  mn in the curren
29df0 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
29e00 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a  ult set for the.
29e10 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
29e20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29e30 20 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74   S into a 64-bit
29e40 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
29e50 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
29e60 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
29e70 66 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a  f that integer..
29e80 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 31 7d 20 54  **.** {H13821} T
29e90 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
29ea0 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69 6e  mn_text(S,N)] in
29eb0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
29ec0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
29ed0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
29ee0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
29ef0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
29f00 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
29f10 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
29f20 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
29f30 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
29f40 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20  ed UTF-8.**     
29f50 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
29f60 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
29f70 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
29f80 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 34 7d  ..**.** {H13824}
29f90 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
29fa0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29  lumn_text16(S,N)
29fb0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
29fc0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
29fd0 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
29fe0 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
29ff0 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2a000 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20   set for the.** 
2a010 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
2a020 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2a030 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
2a040 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a  inated 2-byte.**
2a050 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65            aligne
2a060 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  d UTF-16 native 
2a070 62 79 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e  byte order strin
2a080 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2a090 20 20 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e            a poin
2a0a0 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
2a0b0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32  ng..**.** {H1382
2a0c0 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
2a0d0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e 29  column_type(S,N)
2a0e0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2a0f0 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
2a100 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e  one of [SQLITE_N
2a110 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e  ULL], [SQLITE_IN
2a120 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f  TEGER], [SQLITE_
2a130 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20  FLOAT],.**      
2a140 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54      [SQLITE_TEXT
2a150 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c  ], or [SQLITE_BL
2a160 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61  OB] as appropria
2a170 74 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20  te for.**       
2a180 20 20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d     the Nth colum
2a190 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
2a1a0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2a1b0 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20  lt set for.**   
2a1c0 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70         the [prep
2a1d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a1e0 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 33 30  S..**.** {H13830
2a1f0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2a200 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e 29  olumn_value(S,N)
2a210 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
2a220 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20  rns a.**        
2a230 20 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20    pointer to an 
2a240 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2a250 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2a260 63 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  ct for the.**   
2a270 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
2a280 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
2a290 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2a2a0 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20  lt set for.**   
2a2b0 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70         the [prep
2a2c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a2d0 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  S..*/.const void
2a2e0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2a2f0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
2a300 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2a310 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2a320 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
2a330 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2a340 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2a350 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
2a360 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a370 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
2a380 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
2a390 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2a3a0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2a3b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2a3c0 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
2a3d0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2a3e0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
2a3f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2a400 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2a410 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
2a420 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
2a430 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2a440 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2a450 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2a460 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2a470 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2a480 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2a490 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2a4a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a4b0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2a4c0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
2a4d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
2a4e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2a4f0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2a500 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
2a510 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
2a520 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
2a530 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
2a540 20 7b 48 31 33 33 30 30 7d 20 3c 53 37 30 33 30   {H13300} <S7030
2a550 30 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a  0><S30100>.**.**
2a560 20 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e   The sqlite3_fin
2a570 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e  alize() function
2a580 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65   is called to de
2a590 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64  lete a [prepared
2a5a0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2a5b0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
2a5c0 20 77 61 73 20 65 78 65 63 75 74 65 64 20 73 75   was executed su
2a5d0 63 63 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f  ccessfully or no
2a5e0 74 20 65 78 65 63 75 74 65 64 20 61 74 20 61 6c  t executed at al
2a5f0 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54  l, then.** SQLIT
2a600 45 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64  E_OK is returned
2a610 2e 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f  . If execution o
2a620 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
2a630 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a  failed then an.*
2a640 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  * [error code] o
2a650 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
2a660 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
2a670 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ned..**.** This 
2a680 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
2a690 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
2a6a0 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 78  nt during the ex
2a6b0 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ecution of the.*
2a6c0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2a6d0 65 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20  ement].  If the 
2a6e0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
2a6f0 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c  has not.** compl
2a700 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77  eted execution w
2a710 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
2a720 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74   is called, that
2a730 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f   is like.** enco
2a740 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f  untering an erro
2a750 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
2a760 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74  _interrupt | int
2a770 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f  errupt]..** Inco
2a780 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d  mplete updates m
2a790 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ay be rolled bac
2a7a0 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f  k and transactio
2a7b0 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20  ns canceled,.** 
2a7c0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
2a7d0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
2a7e0 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f  and the.** [erro
2a7f0 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64  r code] returned
2a800 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45   will be [SQLITE
2a810 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49  _ABORT]..**.** I
2a820 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
2a830 20 7b 48 31 31 33 30 32 7d 20 54 68 65 20 5b 73   {H11302} The [s
2a840 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2a850 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65  S)] interface de
2a860 73 74 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20 20  stroys the.**   
2a870 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
2a880 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 6e   statement] S an
2a890 64 20 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a  d releases all.*
2a8a0 2a 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72  *          memor
2a8b0 79 20 61 6e 64 20 66 69 6c 65 20 72 65 73 6f 75  y and file resou
2a8c0 72 63 65 73 20 68 65 6c 64 20 62 79 20 74 68 61  rces held by tha
2a8d0 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  t object..**.** 
2a8e0 7b 48 31 31 33 30 34 7d 20 49 66 20 74 68 65 20  {H11304} If the 
2a8f0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2a900 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2a910 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
2a920 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
2a930 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2a940 20 72 65 74 75 72 6e 65 64 20 61 6e 20 65 72 72   returned an err
2a950 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  or,.**          
2a960 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  then [sqlite3_fi
2a970 6e 61 6c 69 7a 65 28 53 29 5d 20 72 65 74 75 72  nalize(S)] retur
2a980 6e 73 20 74 68 61 74 20 73 61 6d 65 20 65 72 72  ns that same err
2a990 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  or..*/.int sqlit
2a9a0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
2a9b0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2a9c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a9d0 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
2a9e0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
2a9f0 6a 65 63 74 20 7b 48 31 33 33 33 30 7d 20 3c 53  ject {H13330} <S
2aa00 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  70300>.**.** The
2aa10 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
2aa20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
2aa30 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
2aa40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2aa50 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
2aa60 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
2aa70 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
2aa80 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
2aa90 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61  ..** Any SQL sta
2aaa0 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
2aab0 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
2aac0 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
2aad0 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
2aae0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
2aaf0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2ab00 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
2ab10 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
2ab20 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
2ab30 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
2ab40 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
2ab50 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  ngs..**.** {H113
2ab60 33 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  32} The [sqlite3
2ab70 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
2ab80 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
2ab90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2aba0 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20  ent] S.**       
2abb0 20 20 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62     back to the b
2abc0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
2abd0 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b  program..**.** {
2abe0 48 31 31 33 33 34 7d 20 49 66 20 74 68 65 20 6d  H11334} If the m
2abf0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2ac00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2ac10 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
2ac20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
2ac30 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2ac40 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2ac50 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
2ac60 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20 20  _DONE],.**      
2ac70 20 20 20 20 6f 72 20 69 66 20 5b 73 71 6c 69 74      or if [sqlit
2ac80 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
2ac90 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
2aca0 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
2acb0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
2acc0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2acd0 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
2ace0 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  TE_OK]..**.** {H
2acf0 31 31 33 33 36 7d 20 49 66 20 74 68 65 20 6d 6f  11336} If the mo
2ad00 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2ad10 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2ad20 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  S)] for the.**  
2ad30 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
2ad40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2ad50 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
2ad60 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  r, then.**      
2ad70 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
2ad80 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
2ad90 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
2ada0 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
2adb0 2a 20 7b 48 31 31 33 33 38 7d 20 54 68 65 20 5b  * {H11338} The [
2adc0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2add0 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
2ade0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
2adf0 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20  values.**       
2ae00 20 20 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74     of any [sqlit
2ae10 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e  e3_bind_blob|bin
2ae20 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70  dings] on the [p
2ae30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ae40 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  t] S..*/.int sql
2ae50 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
2ae60 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2ae70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ae80 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
2ae90 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
2aea0 6e 73 20 7b 48 31 36 31 30 30 7d 20 3c 53 32 30  ns {H16100} <S20
2aeb0 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  200>.** KEYWORDS
2aec0 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
2aed0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
2aee0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
2aef0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2af00 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
2af10 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
2af20 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2af30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
2af40 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f 20  **.** These two 
2af50 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
2af60 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
2af70 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
2af80 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
2af90 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
2afa0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
2afb0 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
2afc0 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
2afd0 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
2afe0 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
2aff0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
2b000 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
2b010 64 69 66 66 65 72 65 6e 63 65 20 62 65 74 77 65  difference betwe
2b020 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73  en the.** two is
2b030 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
2b040 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 20   parameter, the 
2b050 6e 61 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61  name of the (sca
2b060 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72  lar) function or
2b070 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2c 20 69  .** aggregate, i
2b080 73 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  s encoded in UTF
2b090 2d 38 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  -8 for sqlite3_c
2b0a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2b0b0 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66   and UTF-16.** f
2b0c0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2b0d0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a  e_function16()..
2b0e0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
2b0f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2b100 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2b110 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20  ction] to which 
2b120 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
2b130 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64  ion is to be add
2b140 65 64 2e 20 20 49 66 20 61 20 73 69 6e 67 6c 65  ed.  If a single
2b150 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f   program uses mo
2b160 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
2b170 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
2b180 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74  on internally, t
2b190 68 65 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  hen SQL function
2b1a0 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 20  s must be added 
2b1b0 69 6e 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 0a  individually to.
2b1c0 2a 2a 20 65 61 63 68 20 64 61 74 61 62 61 73 65  ** each database
2b1d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a   connection..**.
2b1e0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
2b1f0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
2b200 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
2b210 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
2b220 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
2b230 66 69 6e 65 64 2e 20 20 54 68 65 20 6c 65 6e 67  fined.  The leng
2b240 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
2b250 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
2b260 20 62 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76   bytes, exclusiv
2b270 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f  e of.** the zero
2b280 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f  -terminator.  No
2b290 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
2b2a0 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73   length limit is
2b2b0 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a   in bytes, not.*
2b2c0 2a 20 63 68 61 72 61 63 74 65 72 73 2e 20 20 41  * characters.  A
2b2d0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
2b2e0 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
2b2f0 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
2b300 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
2b310 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  t in [SQLITE_ERR
2b320 4f 52 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e  OR] being return
2b330 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  ed..**.** The th
2b340 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
2b350 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
2b360 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
2b370 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2b380 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
2b390 61 6b 65 73 2e 20 49 66 20 74 68 69 73 20 70 61  akes. If this pa
2b3a0 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74  rameter is negat
2b3b0 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51  ive, then the SQ
2b3c0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2b3d0 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
2b3e0 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
2b3f0 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  f arguments..**.
2b400 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  ** The fourth pa
2b410 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
2b420 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
2b430 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
2b440 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
2b450 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
2b460 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
2b470 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
2b480 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e  rs.  Any SQL fun
2b490 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2b4a0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61  tion should be a
2b4b0 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ble to work.** w
2b4c0 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20  ork with UTF-8, 
2b4d0 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
2b4e0 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
2b4f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2b500 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
2b510 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
2b520 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
2b530 20 61 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73   another.  It is
2b540 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69   allowed to.** i
2b550 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72  nvoke sqlite3_cr
2b560 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
2b570 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2b580 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d  e_function16() m
2b590 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73  ultiple.** times
2b5a0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
2b5b0 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68  unction but with
2b5c0 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65   different value
2b5d0 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a  s of eTextRep..*
2b5e0 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20  * When multiple 
2b5f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2b600 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
2b610 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
2b620 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
2b630 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
2b640 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
2b650 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
2b660 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
2b670 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
2b680 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
2b690 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2b6a0 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
2b6b0 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20  re what text.** 
2b6c0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
2b6d0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
2b6e0 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
2b6f0 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59  d be [SQLITE_ANY
2b700 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66  ]..**.** The fif
2b710 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2b720 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
2b730 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
2b740 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
2b750 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  .** function can
2b760 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
2b770 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
2b780 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ng [sqlite3_user
2b790 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _data()]..**.** 
2b7a0 54 68 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67  The seventh, eig
2b7b0 68 74 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61  hth and ninth pa
2b7c0 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
2b7d0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
2b7e0 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
2b7f0 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
2b800 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
2b810 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
2b820 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2b830 20 61 67 67 72 65 67 61 74 65 2e 20 41 20 73 63   aggregate. A sc
2b840 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
2b850 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
2b860 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2b870 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c  the xFunc.** cal
2b880 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c  lback only, NULL
2b890 20 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64   pointers should
2b8a0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
2b8b0 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
2b8c0 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
2b8d0 2e 20 41 6e 20 61 67 67 72 65 67 61 74 65 20 53  . An aggregate S
2b8e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
2b8f0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
2b900 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
2b910 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
2b920 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65  d NULL should be
2b930 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
2b940 63 2e 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  c. To delete an 
2b950 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
2b960 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
2b970 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
2b980 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
2b990 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
2b9a0 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70  s..**.** It is p
2b9b0 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69  ermitted to regi
2b9c0 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d  ster multiple im
2b9d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2b9e0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e   the same.** fun
2b9f0 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20  ctions with the 
2ba00 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69  same name but wi
2ba10 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72  th either differ
2ba20 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a  ing numbers of.*
2ba30 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64  * arguments or d
2ba40 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72  iffering preferr
2ba50 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
2ba60 73 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  s.  SQLite will 
2ba70 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
2ba80 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63  mentation most c
2ba90 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
2baa0 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
2bab0 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
2bac0 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
2bad0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2bae0 2a 0a 2a 2a 20 7b 48 31 36 31 30 33 7d 20 54 68  *.** {H16103} Th
2baf0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2bb00 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
2bb10 69 6e 74 65 72 66 61 63 65 20 62 65 68 61 76 65  interface behave
2bb20 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20  s exactly.**    
2bb30 20 20 20 20 20 20 6c 69 6b 65 20 5b 73 71 6c 69        like [sqli
2bb40 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2bb50 69 6f 6e 28 29 5d 20 69 6e 20 65 76 65 72 79 20  ion()] in every 
2bb60 77 61 79 20 65 78 63 65 70 74 20 74 68 61 74 20  way except that 
2bb70 69 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  it.**          i
2bb80 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 7a 46  nterprets the zF
2bb90 75 6e 63 74 69 6f 6e 4e 61 6d 65 20 61 72 67 75  unctionName argu
2bba0 6d 65 6e 74 20 61 73 20 7a 65 72 6f 2d 74 65 72  ment as zero-ter
2bbb0 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 0a 2a  minated UTF-16.*
2bbc0 2a 20 20 20 20 20 20 20 20 20 20 6e 61 74 69 76  *          nativ
2bbd0 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73  e byte order ins
2bbe0 74 65 61 64 20 6f 66 20 61 73 20 7a 65 72 6f 2d  tead of as zero-
2bbf0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
2bc00 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 36 7d  ..**.** {H16106}
2bc10 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
2bc20 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20  vocation of.**  
2bc30 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c          the [sql
2bc40 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2bc50 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e  tion(D,X,N,E,...
2bc60 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
2bc70 69 73 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20  isters.**       
2bc80 20 20 20 6f 72 20 72 65 70 6c 61 63 65 73 20 63     or replaces c
2bc90 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2bca0 73 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61  s in the [databa
2bcb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
2bcc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 73 65  .**          use
2bcd0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  d to implement t
2bce0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2bcf0 6e 61 6d 65 64 20 58 20 77 69 74 68 20 4e 20 70  named X with N p
2bd00 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20  arameters.**    
2bd10 20 20 20 20 20 20 61 6e 64 20 68 61 76 69 6e 67        and having
2bd20 20 61 20 70 72 65 66 65 72 72 65 64 20 74 65 78   a preferred tex
2bd30 74 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 45 2e  t encoding of E.
2bd40 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 39 7d 20  .**.** {H16109} 
2bd50 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
2bd60 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  l to [sqlite3_cr
2bd70 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2bd80 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a  X,N,E,P,F,S,L)].
2bd90 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 70 6c  **          repl
2bda0 61 63 65 73 20 74 68 65 20 50 2c 20 46 2c 20 53  aces the P, F, S
2bdb0 2c 20 61 6e 64 20 4c 20 76 61 6c 75 65 73 20 66  , and L values f
2bdc0 72 6f 6d 20 61 6e 79 20 70 72 69 6f 72 20 63 61  rom any prior ca
2bdd0 6c 6c 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  lls with.**     
2bde0 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 44 2c       the same D,
2bdf0 20 58 2c 20 4e 2c 20 61 6e 64 20 45 20 76 61 6c   X, N, and E val
2be00 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  ues..**.** {H161
2be10 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  12} The [sqlite3
2be20 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2be30 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  (D,X,...)] inter
2be40 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 0a  face fails with.
2be50 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65  **          a re
2be60 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51  turn code of [SQ
2be70 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 74  LITE_ERROR] if t
2be80 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2be90 6e 61 6d 65 20 58 20 69 73 0a 2a 2a 20 20 20 20  name X is.**    
2bea0 20 20 20 20 20 20 6c 6f 6e 67 65 72 20 74 68 61        longer tha
2beb0 6e 20 32 35 35 20 62 79 74 65 73 20 65 78 63 6c  n 255 bytes excl
2bec0 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72  usive of the zer
2bed0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
2bee0 0a 2a 2a 20 7b 48 31 36 31 31 38 7d 20 45 69 74  .** {H16118} Eit
2bef0 68 65 72 20 46 20 6d 75 73 74 20 62 65 20 4e 55  her F must be NU
2bf00 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61  LL and S and L a
2bf10 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72 20 65  re non-NULL or e
2bf20 6c 73 65 20 46 0a 2a 2a 20 20 20 20 20 20 20 20  lse F.**        
2bf30 20 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e    is non-NULL an
2bf40 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20 4e 55  d S and L are NU
2bf50 4c 4c 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a  LL, otherwise.**
2bf60 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2bf70 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2bf80 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53  on(D,X,N,E,P,F,S
2bf90 2c 4c 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  ,L)] returns [SQ
2bfa0 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a 2a 0a  LITE_ERROR]..**.
2bfb0 2a 2a 20 7b 48 31 36 31 32 31 7d 20 54 68 65 20  ** {H16121} The 
2bfc0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2bfd0 66 75 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e 29 5d  function(D,...)]
2bfe0 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
2bff0 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20   with an.**     
2c000 20 20 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20       error code 
2c010 6f 66 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  of [SQLITE_BUSY]
2c020 20 69 66 20 74 68 65 72 65 20 65 78 69 73 74 20   if there exist 
2c030 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c040 65 6e 74 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ents].**        
2c050 20 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74    associated wit
2c060 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
2c070 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
2c080 2a 0a 2a 2a 20 7b 48 31 36 31 32 34 7d 20 54 68  *.** {H16124} Th
2c090 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2c0a0 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2c0b0 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
2c0c0 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a   fails with an.*
2c0d0 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f 72  *          error
2c0e0 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
2c0f0 5f 45 52 52 4f 52 5d 20 69 66 20 70 61 72 61 6d  _ERROR] if param
2c100 65 74 65 72 20 4e 20 28 73 70 65 63 69 66 79 69  eter N (specifyi
2c110 6e 67 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a  ng the number.**
2c120 20 20 20 20 20 20 20 20 20 20 6f 66 20 61 72 67            of arg
2c130 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51  uments to the SQ
2c140 4c 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  L function being
2c150 20 72 65 67 69 73 74 65 72 65 64 29 20 69 73 20   registered) is 
2c160 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  less.**         
2c170 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
2c180 74 65 72 20 74 68 61 6e 20 31 32 37 2e 0a 2a 2a  ter than 127..**
2c190 0a 2a 2a 20 7b 48 31 36 31 32 37 7d 20 57 68 65  .** {H16127} Whe
2c1a0 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  n N is non-negat
2c1b0 69 76 65 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ive, the [sqlite
2c1c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2c1d0 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a  n(D,X,N,...)].**
2c1e0 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66            interf
2c1f0 61 63 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62  ace causes callb
2c200 61 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b  acks to be invok
2c210 65 64 20 66 6f 72 20 74 68 65 20 53 51 4c 20 66  ed for the SQL f
2c220 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20  unction.**      
2c230 20 20 20 20 6e 61 6d 65 64 20 58 20 77 68 65 6e      named X when
2c240 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
2c250 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
2c260 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  SQL function is.
2c270 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 61 63  **          exac
2c280 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  tly N..**.** {H1
2c290 36 31 33 30 7d 20 57 68 65 6e 20 4e 20 69 73 20  6130} When N is 
2c2a0 2d 31 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  -1, the [sqlite3
2c2b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c2c0 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20  (D,X,N,...)].** 
2c2d0 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
2c2e0 63 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61  ce causes callba
2c2f0 63 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  cks to be invoke
2c300 64 20 66 6f 72 20 74 68 65 20 53 51 4c 20 66 75  d for the SQL fu
2c310 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  nction.**       
2c320 20 20 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20     named X with 
2c330 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  any number of ar
2c340 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b  guments..**.** {
2c350 48 31 36 31 33 33 7d 20 57 68 65 6e 20 63 61 6c  H16133} When cal
2c360 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ls to [sqlite3_c
2c370 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2c380 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  ,X,N,...)].**   
2c390 20 20 20 20 20 20 20 73 70 65 63 69 66 79 20 6d         specify m
2c3a0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
2c3b0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
2c3c0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a  ame function X.*
2c3d0 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 77  *          and w
2c3e0 68 65 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d 65 6e  hen one implemen
2c3f0 74 61 74 69 6f 6e 20 68 61 73 20 4e 3e 3d 30 20  tation has N>=0 
2c400 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 68 61  and the other ha
2c410 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20 20 20  s N=(-1).**     
2c420 20 20 20 20 20 74 68 65 20 69 6d 70 6c 65 6d 65       the impleme
2c430 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e  ntation with a n
2c440 6f 6e 2d 7a 65 72 6f 20 4e 20 69 73 20 70 72 65  on-zero N is pre
2c450 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ferred..**.** {H
2c460 31 36 31 33 36 7d 20 57 68 65 6e 20 63 61 6c 6c  16136} When call
2c470 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  s to [sqlite3_cr
2c480 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2c490 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  X,N,E,...)].**  
2c4a0 20 20 20 20 20 20 20 20 73 70 65 63 69 66 79 20          specify 
2c4b0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
2c4c0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
2c4d0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 20  same function X 
2c4e0 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  with.**         
2c4f0 20 74 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72   the same number
2c500 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 4e 20   of arguments N 
2c510 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65  but with differe
2c520 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  nt.**          e
2c530 6e 63 6f 64 69 6e 67 73 20 45 2c 20 74 68 65 6e  ncodings E, then
2c540 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
2c550 69 6f 6e 20 77 68 65 72 65 20 45 20 6d 61 74 63  ion where E matc
2c560 68 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  hes the.**      
2c570 20 20 20 20 64 61 74 61 62 61 73 65 20 65 6e 63      database enc
2c580 6f 64 69 6e 67 20 69 73 20 70 72 65 66 65 72 72  oding is preferr
2c590 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33  ed..**.** {H1613
2c5a0 39 7d 20 46 6f 72 20 61 6e 20 61 67 67 72 65 67  9} For an aggreg
2c5b0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2c5c0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
2c5d0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
2c5e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2c5f0 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c  ion(D,X,N,E,P,0,
2c600 53 2c 4c 29 5d 20 74 68 65 20 66 69 6e 61 6c 69  S,L)] the finali
2c610 7a 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  zer.**          
2c620 66 75 6e 63 74 69 6f 6e 20 4c 20 77 69 6c 6c 20  function L will 
2c630 61 6c 77 61 79 73 20 62 65 20 69 6e 76 6f 6b 65  always be invoke
2c640 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 69  d exactly once i
2c650 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2c660 20 20 73 74 65 70 20 66 75 6e 63 74 69 6f 6e 20    step function 
2c670 53 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65 20  S is called one 
2c680 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
2c690 2a 0a 2a 2a 20 7b 48 31 36 31 34 32 7d 20 57 68  *.** {H16142} Wh
2c6a0 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
2c6b0 73 20 65 69 74 68 65 72 20 74 68 65 20 78 46 75  s either the xFu
2c6c0 6e 63 20 6f 72 20 78 53 74 65 70 20 66 75 6e 63  nc or xStep func
2c6d0 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20  tion of.**      
2c6e0 20 20 20 20 61 6e 20 61 70 70 6c 69 63 61 74 69      an applicati
2c6f0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2c700 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
2c710 67 61 74 65 20 63 72 65 61 74 65 64 0a 2a 2a 20  gate created.** 
2c720 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c           by [sql
2c730 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2c740 74 69 6f 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69  tion()] or [sqli
2c750 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2c760 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20  ion16()],.**    
2c770 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 61        then the a
2c780 72 72 61 79 20 6f 66 20 5b 73 71 6c 69 74 65 33  rray of [sqlite3
2c790 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 20  _value] objects 
2c7a0 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a  passed as the.**
2c7b0 20 20 20 20 20 20 20 20 20 20 74 68 69 72 64 20            third 
2c7c0 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 61 6c  parameter are al
2c7d0 77 61 79 73 20 5b 70 72 6f 74 65 63 74 65 64 20  ways [protected 
2c7e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2c7f0 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73  bjects..*/.int s
2c800 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2c810 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
2c820 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
2c830 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
2c840 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2c850 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2c860 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2c870 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2c880 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2c890 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2c8a0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2c8b0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2c8c0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2c8d0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2c8e0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2c8f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
2c900 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2c910 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2c920 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
2c930 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
2c940 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
2c950 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
2c960 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
2c970 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
2c980 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
2c990 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2c9a0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2c9b0 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
2c9c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2c9d0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2c9e0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
2c9f0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
2ca00 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  ntext*).);../*.*
2ca10 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
2ca20 20 45 6e 63 6f 64 69 6e 67 73 20 7b 48 31 30 32   Encodings {H102
2ca30 36 37 7d 20 3c 53 35 30 32 30 30 3e 20 3c 48 31  67} <S50200> <H1
2ca40 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6100>.**.** Thes
2ca50 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
2ca60 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
2ca70 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
2ca80 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
2ca90 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
2caa0 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
2cab0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
2cac0 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
2cad0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
2cae0 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
2caf0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2cb00 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
2cb10 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
2cb20 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
2cb30 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
2cb40 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2cb50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2cb60 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
2cb70 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    5    /* sqlite
2cb80 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2cb90 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  n only */.#defin
2cba0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
2cbb0 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
2cbc0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2cbd0 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
2cbe0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2cbf0 3a 20 4f 62 73 6f 6c 65 74 65 20 46 75 6e 63 74  : Obsolete Funct
2cc00 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
2cc10 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61   functions are a
2cc20 6c 6c 20 6e 6f 77 20 6f 62 73 6f 6c 65 74 65 2e  ll now obsolete.
2cc30 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
2cc40 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
2cc50 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
2cc60 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
2cc70 65 2c 20 77 65 20 63 6f 6e 74 69 6e 75 65 20 74  e, we continue t
2cc80 6f 20 73 75 70 70 6f 72 74 0a 2a 2a 20 74 68 65  o support.** the
2cc90 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 48  se functions.  H
2cca0 6f 77 65 76 65 72 2c 20 6e 65 77 20 64 65 76 65  owever, new deve
2ccb0 6c 6f 70 6d 65 6e 74 20 70 72 6f 6a 65 63 74 73  lopment projects
2ccc0 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a   should avoid.**
2ccd0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73   the use of thes
2cce0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f  e functions.  To
2ccf0 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20   help encourage 
2cd00 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a  people to avoid.
2cd10 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66  ** using these f
2cd20 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65  unctions, we are
2cd30 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65   not going to te
2cd40 6c 6c 20 79 6f 75 20 77 61 6e 74 20 74 68 65 79  ll you want they
2cd50 20 64 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69   do..*/.int sqli
2cd60 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2cd70 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
2cd80 65 78 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  ext*);.int sqlit
2cd90 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
2cda0 65 33 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73  e3_stmt*);.int s
2cdb0 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
2cdc0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
2cdd0 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
2cde0 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  stmt*);.int sqli
2cdf0 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
2ce00 65 72 28 76 6f 69 64 29 3b 0a 76 6f 69 64 20 73  er(void);.void s
2ce10 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
2ce20 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 69 6e 74  eanup(void);.int
2ce30 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
2ce40 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
2ce50 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
2ce60 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c  4,int),void*,sql
2ce70 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a  ite3_int64);../*
2ce80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
2ce90 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63  taining SQL Func
2cea0 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56  tion Parameter V
2ceb0 61 6c 75 65 73 20 7b 48 31 35 31 30 30 7d 20 3c  alues {H15100} <
2cec0 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
2ced0 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
2cee0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
2cef0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
2cf00 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
2cf10 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
2cf20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
2cf30 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
2cf40 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
2cf50 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
2cf60 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
2cf70 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75  e..**.** The xFu
2cf80 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
2cf90 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
2cfa0 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
2cfb0 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
2cfc0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
2cfd0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2cfe0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
2cff0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2d000 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
2d010 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
2d020 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
2d030 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
2d040 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34  egates..** The 4
2d050 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2d060 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
2d070 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
2d080 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
2d090 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d0a0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2d0b0 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
2d0c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2d0d0 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
2d0e0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2d0f0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
2d100 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
2d110 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
2d120 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
2d130 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
2d140 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2d150 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2d160 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
2d170 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
2d180 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2d190 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
2d1a0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
2d1b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
2d1c0 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
2d1d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
2d1e0 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
2d1f0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
2d200 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  havior..**.** Th
2d210 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
2d220 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
2d230 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
2d240 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2d250 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
2d260 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f  t that  these ro
2d270 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
2d280 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
2d290 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2d2a0 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
2d2b0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
2d2c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
2d2d0 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
2d2e0 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
2d2f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
2d300 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2d310 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
2d320 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36  xtracts a UTF-16
2d330 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
2d340 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
2d350 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
2d360 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a  machine.  The.**
2d370 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2d380 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
2d390 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2d3a0 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
2d3b0 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
2d3c0 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
2d3d0 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
2d3e0 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
2d3f0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
2d400 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
2d410 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
2d420 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
2d430 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
2d440 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
2d450 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
2d460 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
2d470 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
2d480 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
2d490 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
2d4a0 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
2d4b0 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
2d4c0 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
2d4d0 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
2d4e0 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
2d4f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
2d500 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
2d510 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
2d520 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
2d530 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
2d540 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
2d550 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
2d560 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
2d570 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
2d580 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
2d590 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
2d5a0 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
2d5b0 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
2d5c0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2d5d0 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
2d5e0 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
2d5f0 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
2d600 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
2d610 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
2d620 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2d630 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
2d640 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
2d650 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
2d660 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
2d670 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
2d680 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
2d690 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2d6a0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2d6b0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2d6c0 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
2d6d0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2d6e0 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
2d6f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2d700 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  t16()]..**.** Th
2d710 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
2d720 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2d730 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2d740 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
2d750 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
2d760 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
2d770 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
2d780 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  eters..**.** INV
2d790 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
2d7a0 48 31 35 31 30 33 7d 20 54 68 65 20 5b 73 71 6c  H15103} The [sql
2d7b0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
2d7c0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
2d7d0 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2d7e0 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
2d7f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2d800 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
2d810 20 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e 0a 2a   BLOB and then.*
2d820 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2d830 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2d840 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61  the converted va
2d850 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  lue..**.** {H151
2d860 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  06} The [sqlite3
2d870 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 56 29 5d  _value_bytes(V)]
2d880 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2d890 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
2d8a0 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74     number of byt
2d8b0 65 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f  es in the BLOB o
2d8c0 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73  r string (exclus
2d8d0 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ive of the.**   
2d8e0 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d         zero term
2d8f0 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74  inator on the st
2d900 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72  ring) that was r
2d910 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
2d920 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20  *          most 
2d930 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2d940 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2d950 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  ob(V)] or.**    
2d960 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76        [sqlite3_v
2d970 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a  alue_text(V)]..*
2d980 2a 0a 2a 2a 20 7b 48 31 35 31 30 39 7d 20 54 68  *.** {H15109} Th
2d990 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2d9a0 5f 62 79 74 65 73 31 36 28 56 29 5d 20 69 6e 74  _bytes16(V)] int
2d9b0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2d9c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
2d9d0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2d9e0 6e 20 74 68 65 20 73 74 72 69 6e 67 20 28 65 78  n the string (ex
2d9f0 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a  clusive of the.*
2da00 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
2da10 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68  terminator on th
2da20 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77  e string) that w
2da30 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  as returned by t
2da40 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  he.**          m
2da50 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2da60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  to [sqlite3_valu
2da70 65 5f 74 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a  e_text16(V)],.**
2da80 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
2da90 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
2daa0 65 28 56 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  e(V)], or [sqlit
2dab0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
2dac0 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  e(V)]..**.** {H1
2dad0 35 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  5112} The [sqlit
2dae0 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
2daf0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
2db00 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2db10 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
2db20 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2db30 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
2db40 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2db50 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20  value and.**    
2db60 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
2db70 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c  copy of that val
2db80 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31  ue..**.** {H1511
2db90 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
2dba0 76 61 6c 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e  value_int(V)] in
2dbb0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
2dbc0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2dbd0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2dbe0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2dbf0 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  t V into a 64-bi
2dc00 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2dc10 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
2dc20 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77   returns the low
2dc30 65 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 68  er 32 bits of th
2dc40 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  at integer..**.*
2dc50 2a 20 7b 48 31 35 31 31 38 7d 20 54 68 65 20 5b  * {H15118} The [
2dc60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
2dc70 74 36 34 28 56 29 5d 20 69 6e 74 65 72 66 61 63  t64(V)] interfac
2dc80 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
2dc90 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
2dca0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2dcb0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
2dcc0 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e  to a 64-bit sign
2dcd0 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a  ed integer and.*
2dce0 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
2dcf0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61  ns a copy of tha
2dd00 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
2dd10 20 7b 48 31 35 31 32 31 7d 20 54 68 65 20 5b 73   {H15121} The [s
2dd20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2dd30 74 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(V)] interface 
2dd40 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2dd50 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
2dd60 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2dd70 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
2dd80 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2dd90 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20  ed UTF-8.**     
2dda0 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
2ddb0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2ddc0 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
2ddd0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 34 7d  ..**.** {H15124}
2dde0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2ddf0 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 20 69  lue_text16(V)] i
2de00 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2de10 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2de20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2de30 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2de40 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f  ct V into a zero
2de50 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79  -terminated 2-by
2de60 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
2de70 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61  ligned UTF-16 na
2de80 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a  tive byte order.
2de90 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
2dea0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
2deb0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
2dec0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
2ded0 48 31 35 31 32 37 7d 20 54 68 65 20 5b 73 71 6c  H15127} The [sql
2dee0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2def0 36 62 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  6be(V)] interfac
2df00 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
2df10 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
2df20 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2df30 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
2df40 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2df50 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20  ated 2-byte.**  
2df60 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20          aligned 
2df70 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61  UTF-16 big-endia
2df80 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  n.**          st
2df90 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2dfa0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2dfb0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
2dfc0 20 7b 48 31 35 31 33 30 7d 20 54 68 65 20 5b 73   {H15130} The [s
2dfd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2dfe0 74 31 36 6c 65 28 56 29 5d 20 69 6e 74 65 72 66  t16le(V)] interf
2dff0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2e000 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2e010 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e020 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
2e030 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
2e040 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a  inated 2-byte.**
2e050 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65            aligne
2e060 64 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d  d UTF-16 little-
2e070 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20  endian.**       
2e080 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
2e090 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2e0a0 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
2e0b0 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 33 7d 20 54  **.** {H15133} T
2e0c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2e0d0 65 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72  e_type(V)] inter
2e0e0 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
2e0f0 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20           one of 
2e100 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b  [SQLITE_NULL], [
2e110 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
2e120 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
2e130 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
2e140 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b  LITE_TEXT], or [
2e150 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20  SQLITE_BLOB] as 
2e160 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a  appropriate for.
2e170 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2e180 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2e190 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20  object V..**.** 
2e1a0 7b 48 31 35 31 33 36 7d 20 54 68 65 20 5b 73 71  {H15136} The [sq
2e1b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
2e1c0 72 69 63 5f 74 79 70 65 28 56 29 5d 20 69 6e 74  ric_type(V)] int
2e1d0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 0a  erface converts.
2e1e0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2e1f0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2e200 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2e210 20 56 20 69 6e 74 6f 20 65 69 74 68 65 72 20 61   V into either a
2e220 6e 20 69 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20  n integer or.** 
2e230 20 20 20 20 20 20 20 20 20 61 20 66 6c 6f 61 74           a float
2e240 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
2e250 69 66 20 69 74 20 63 61 6e 20 64 6f 20 73 6f 20  if it can do so 
2e260 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a  without loss of.
2e270 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f  **          info
2e280 72 6d 61 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74  rmation, and ret
2e290 75 72 6e 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  urns one of [SQL
2e2a0 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20  ITE_NULL],.**   
2e2b0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49         [SQLITE_I
2e2c0 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45  NTEGER], [SQLITE
2e2d0 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
2e2e0 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20  _TEXT], or.**   
2e2f0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 42         [SQLITE_B
2e300 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69  LOB] as appropri
2e310 61 74 65 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  ate for the.**  
2e320 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
2e330 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2e340 5d 20 6f 62 6a 65 63 74 20 56 20 61 66 74 65 72  ] object V after
2e350 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
2e360 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73  attempt..*/.cons
2e370 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2e380 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
2e390 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2e3a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2e3b0 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
2e3c0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2e3d0 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
2e3e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2e3f0 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
2e400 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
2e410 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2e420 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
2e430 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
2e440 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
2e450 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
2e460 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
2e470 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
2e480 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
2e490 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
2e4a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2e4b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2e4c0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2e4d0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2e4e0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2e4f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2e500 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
2e510 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
2e520 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
2e530 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
2e540 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2e550 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
2e560 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2e570 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
2e580 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
2e590 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2e5a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e5b0 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
2e5c0 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
2e5d0 74 65 78 74 20 7b 48 31 36 32 31 30 7d 20 3c 53  text {H16210} <S
2e5e0 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
2e5f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e600 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
2e610 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
2e620 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  his routine to a
2e630 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72  llocate.** a str
2e640 75 63 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69  ucture for stori
2e650 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a  ng their state..
2e660 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
2e670 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
2e680 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2e690 78 74 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  xt() routine is 
2e6a0 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a 2a 2a 20  called for a.** 
2e6b0 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
2e6c0 67 61 74 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c  gate, SQLite all
2e6d0 6f 63 61 74 65 73 20 6e 42 79 74 65 73 20 6f 66  ocates nBytes of
2e6e0 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
2e6f0 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f  out that.** memo
2e700 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
2e710 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e  a pointer to it.
2e720 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73   On second and s
2e730 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
2e740 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
2e750 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2e760 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
2e770 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
2e780 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 68 65 20  n index,.** the 
2e790 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
2e7a0 65 74 75 72 6e 65 64 2e 20 54 68 65 20 69 6d 70  eturned. The imp
2e7b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
2e7c0 68 65 20 61 67 67 72 65 67 61 74 65 20 63 61 6e  he aggregate can
2e7d0 20 75 73 65 0a 2a 2a 20 74 68 65 20 72 65 74 75   use.** the retu
2e7e0 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20 61  rned buffer to a
2e7f0 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a  ccumulate data..
2e800 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 61 75 74  **.** SQLite aut
2e810 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
2e820 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   the allocated b
2e830 75 66 66 65 72 20 77 68 65 6e 20 74 68 65 20 61  uffer when the a
2e840 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 72  ggregate.** quer
2e850 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
2e860 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
2e870 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
2e880 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
2e890 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
2e8a0 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
2e8b0 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
2e8c0 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
2e8d0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
2e8e0 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
2e8f0 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
2e900 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  s the aggregate 
2e910 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2e920 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
2e930 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2e940 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2e950 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
2e960 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
2e970 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2e980 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ng..**.** INVARI
2e990 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ANTS:.**.** {H16
2e9a0 32 31 31 7d 20 54 68 65 20 66 69 72 73 74 20 69  211} The first i
2e9b0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
2e9c0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2e9d0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f  context(C,N)] fo
2e9e0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  r.**          a 
2e9f0 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61  particular insta
2ea00 6e 63 65 20 6f 66 20 61 6e 20 61 67 67 72 65 67  nce of an aggreg
2ea10 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 28 66 6f  ate function (fo
2ea20 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
2ea30 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65  *          conte
2ea40 78 74 20 43 29 20 63 61 75 73 65 73 20 53 51 4c  xt C) causes SQL
2ea50 69 74 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ite to allocate 
2ea60 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
2ea70 79 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  y,.**          z
2ea80 65 72 6f 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  ero that memory,
2ea90 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f   and return a po
2eaa0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 61 6c 6c  inter to the all
2eab0 6f 63 61 74 65 64 20 6d 65 6d 6f 72 79 2e 0a 2a  ocated memory..*
2eac0 2a 0a 2a 2a 20 7b 48 31 36 32 31 33 7d 20 49 66  *.** {H16213} If
2ead0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2eae0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
2eaf0 73 20 64 75 72 69 6e 67 0a 2a 2a 20 20 20 20 20  s during.**     
2eb00 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67       [sqlite3_ag
2eb10 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2eb20 43 2c 4e 29 5d 20 74 68 65 6e 20 74 68 65 20 66  C,N)] then the f
2eb30 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
2eb40 30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 35  0..**.** {H16215
2eb50 7d 20 53 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  } Second and sub
2eb60 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
2eb70 6f 6e 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ons of.**       
2eb80 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72     [sqlite3_aggr
2eb90 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
2eba0 4e 29 5d 20 66 6f 72 20 74 68 65 20 73 61 6d 65  N)] for the same
2ebb0 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
2ebc0 20 43 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69   C.**          i
2ebd0 67 6e 6f 72 65 20 74 68 65 20 4e 20 70 61 72 61  gnore the N para
2ebe0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
2ebf0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2ec00 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
2ec10 20 20 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f     block of memo
2ec20 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ry returned by t
2ec30 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74  he first invocat
2ec40 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  ion..**.** {H162
2ec50 31 37 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  17} The memory a
2ec60 6c 6c 6f 63 61 74 65 64 20 62 79 20 5b 73 71 6c  llocated by [sql
2ec70 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2ec80 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 69 73 0a  ontext(C,N)] is.
2ec90 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f  **          auto
2eca0 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20  matically freed 
2ecb0 6f 6e 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  on the next call
2ecc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2ecd0 65 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  et()].**        
2ece0 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69    or [sqlite3_fi
2ecf0 6e 61 6c 69 7a 65 28 29 5d 20 66 6f 72 20 74 68  nalize()] for th
2ed00 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2ed10 65 6d 65 6e 74 5d 20 63 6f 6e 74 61 69 6e 69 6e  ement] containin
2ed20 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  g.**          th
2ed30 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
2ed40 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20  tion associated 
2ed50 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a  with context C..
2ed60 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
2ed70 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2ed80 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
2ed90 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
2eda0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2edb0 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
2edc0 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32   Functions {H162
2edd0 34 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  40} <S20200>.**.
2ede0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
2edf0 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
2ee00 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
2ee10 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
2ee20 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
2ee30 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
2ee40 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
2ee50 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
2ee60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
2ee70 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2ee80 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2ee90 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2eea0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
2eeb0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
2eec0 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
2eed0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
2eee0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b  ined function. {
2eef0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  END}.**.** This 
2ef00 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
2ef10 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
2ef20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
2ef30 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
2ef40 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2ef50 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
2ef60 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ing..**.** INVAR
2ef70 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
2ef80 36 32 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  6243} The [sqlit
2ef90 65 33 5f 75 73 65 72 5f 64 61 74 61 28 43 29 5d  e3_user_data(C)]
2efa0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2efb0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
2efc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 50 20 70  .**          P p
2efd0 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 20  ointer from the 
2efe0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2eff0 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
2f000 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20  ,P,F,S,L)].**   
2f010 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
2f020 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2f030 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  on16(D,X,N,E,P,F
2f040 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74  ,S,L)] call that
2f050 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
2f060 69 73 74 65 72 65 64 20 74 68 65 20 53 51 4c 20  istered the SQL 
2f070 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61  function associa
2f080 74 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  ted with [sqlite
2f090 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f  3_context] C..*/
2f0a0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
2f0b0 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33  ser_data(sqlite3
2f0c0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
2f0d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
2f0e0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2f0f0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b   For Functions {
2f100 48 31 36 32 35 30 7d 20 3c 53 36 30 36 30 30 3e  H16250} <S60600>
2f110 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20200>.**.** T
2f120 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
2f130 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
2f140 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2f150 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
2f160 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
2f170 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f180 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
2f190 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
2f1a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
2f1b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2f1c0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2f1d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2f1e0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
2f1f0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
2f200 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
2f210 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
2f220 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
2f230 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2f240 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 35 33 7d 20  .**.** {H16253} 
2f250 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
2f260 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 43  text_db_handle(C
2f270 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
2f280 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  urns a copy of t
2f290 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44  he.**          D
2f2a0 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68   pointer from th
2f2b0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2f2c0 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
2f2d0 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20  ,E,P,F,S,L)].** 
2f2e0 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
2f2f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f300 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50  tion16(D,X,N,E,P
2f310 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68  ,F,S,L)] call th
2f320 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  at.**          r
2f330 65 67 69 73 74 65 72 65 64 20 74 68 65 20 53 51  egistered the SQ
2f340 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63  L function assoc
2f350 69 61 74 65 64 20 77 69 74 68 20 5b 73 71 6c 69  iated with [sqli
2f360 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a  te3_context] C..
2f370 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
2f380 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2f390 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
2f3a0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
2f3b0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
2f3c0 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
2f3d0 61 20 7b 48 31 36 32 37 30 7d 20 3c 53 32 30 32  a {H16270} <S202
2f3e0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  00>.**.** The fo
2f3f0 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63  llowing two func
2f400 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65  tions may be use
2f410 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20  d by scalar SQL 
2f420 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
2f430 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
2f440 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
2f450 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
2f460 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
2f470 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
2f480 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
2f490 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
2f4a0 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
2f4b0 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
2f4c0 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
2f4d0 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
2f4e0 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
2f4f0 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
2f500 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a  erved. This may.
2f510 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20  ** be used, for 
2f520 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20  example, to add 
2f530 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
2f540 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63  sion matching sc
2f550 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  alar.** function
2f560 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
2f570 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
2f580 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
2f590 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a   is stored as.**
2f5a0 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
2f5b0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51  ated with the SQ
2f5c0 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  L value passed a
2f5d0 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  s the regular ex
2f5e0 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74  pression.** patt
2f5f0 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c  ern.  The compil
2f600 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  ed regular expre
2f610 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75  ssion can be reu
2f620 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a  sed on multiple.
2f630 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
2f640 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
2f650 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20  ion so that the 
2f660 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e  original pattern
2f670 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20   string.** does 
2f680 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72  not need to be r
2f690 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63  ecompiled on eac
2f6a0 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  h invocation..**
2f6b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2f6c0 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
2f6d0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2f6e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2f6f0 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
2f700 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
2f710 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2f720 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
2f730 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
2f740 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
2f750 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2f760 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2f770 2e 20 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61  . If no metadata
2f780 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a   has been ever.*
2f790 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74  * been set for t
2f7a0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20  he Nth argument 
2f7b0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c  of the function,
2f7c0 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65   or if the corre
2f7d0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63  sponding.** func
2f7e0 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68  tion parameter h
2f7f0 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65  as changed since
2f800 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77   the meta-data w
2f810 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20  as set,.** then 
2f820 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2f830 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20  ata() returns a 
2f840 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2f850 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2f860 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
2f870 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68  terface saves th
2f880 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f  e metadata.** po
2f890 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20  inted to by its 
2f8a0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  3rd parameter as
2f8b0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f   the metadata fo
2f8c0 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
2f8d0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
2f8e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2f8f0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62  d function.  Sub
2f900 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
2f910 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
2f920 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20  auxdata() might 
2f930 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61  return this data
2f940 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e  , if it has.** n
2f950 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65  ot been destroye
2f960 64 2e 0a 2a 2a 20 49 66 20 69 74 20 69 73 20 6e  d..** If it is n
2f970 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
2f980 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
2f990 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75  destructor.** fu
2f9a0 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20  nction given by 
2f9b0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
2f9c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  r to sqlite3_set
2f9d0 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a  _auxdata() on.**
2f9e0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68   the metadata wh
2f9f0 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
2fa00 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
2fa10 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a  rameter changes.
2fa20 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53  ** or when the S
2fa30 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
2fa40 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65  pletes, whicheve
2fa50 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a  r comes first..*
2fa60 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66  *.** SQLite is f
2fa70 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20  ree to call the 
2fa80 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64  destructor and d
2fa90 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20  rop metadata on 
2faa0 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  any.** parameter
2fab0 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e   of any function
2fac0 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 54   at any time.  T
2fad0 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65  he only guarante
2fae0 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  e is that.** the
2faf0 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c   destructor will
2fb00 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
2fb10 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  e the metadata i
2fb20 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a  s dropped..**.**
2fb30 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65   In practice, me
2fb40 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
2fb50 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
2fb60 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
2fb70 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
2fb80 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
2fb90 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
2fba0 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
2fbb0 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
2fbc0 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c   and SQL variabl
2fbd0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es..**.** These 
2fbe0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
2fbf0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
2fc00 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
2fc10 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
2fc20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2fc30 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ning..**.** INVA
2fc40 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
2fc50 31 36 32 37 32 7d 20 54 68 65 20 5b 73 71 6c 69  16272} The [sqli
2fc60 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
2fc70 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,N)] interface 
2fc80 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2fc90 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  r.**          to
2fca0 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
2fcb0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 4e 74  ated with the Nt
2fcc0 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  h parameter of t
2fcd0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a  he SQL function.
2fce0 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 6f 73  **          whos
2fcf0 65 20 63 6f 6e 74 65 78 74 20 69 73 20 43 2c 20  e context is C, 
2fd00 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65  or NULL if there
2fd10 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 20   is no metadata 
2fd20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20  associated.**   
2fd30 20 20 20 20 20 20 20 77 69 74 68 20 74 68 61 74         with that
2fd40 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
2fd50 2a 20 7b 48 31 36 32 37 34 7d 20 54 68 65 20 5b  * {H16274} The [
2fd60 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2fd70 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 6e  ata(C,N,P,D)] in
2fd80 74 65 72 66 61 63 65 20 61 73 73 69 67 6e 73 20  terface assigns 
2fd90 61 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20 20  a metadata.**   
2fda0 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 50         pointer P
2fdb0 20 74 6f 20 74 68 65 20 4e 74 68 20 70 61 72 61   to the Nth para
2fdc0 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c  meter of the SQL
2fdd0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 63   function with c
2fde0 6f 6e 74 65 78 74 20 43 2e 0a 2a 2a 0a 2a 2a 20  ontext C..**.** 
2fdf0 7b 48 31 36 32 37 36 7d 20 53 51 4c 69 74 65 20  {H16276} SQLite 
2fe00 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
2fe10 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74  destructor D wit
2fe20 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  h a single argum
2fe30 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ent.**          
2fe40 77 68 69 63 68 20 69 73 20 74 68 65 20 6d 65 74  which is the met
2fe50 61 64 61 74 61 20 70 6f 69 6e 74 65 72 20 50 20  adata pointer P 
2fe60 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
2fe70 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
2fe80 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
2fe90 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 77  data(C,N,P,D)] w
2fea0 68 65 6e 20 53 51 4c 69 74 65 20 63 65 61 73 65  hen SQLite cease
2feb0 73 20 74 6f 20 68 6f 6c 64 0a 2a 2a 20 20 20 20  s to hold.**    
2fec0 20 20 20 20 20 20 74 68 65 20 6d 65 74 61 64 61        the metada
2fed0 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37  ta..**.** {H1627
2fee0 37 7d 20 53 51 4c 69 74 65 20 63 65 61 73 65 73  7} SQLite ceases
2fef0 20 74 6f 20 68 6f 6c 64 20 6d 65 74 61 64 61 74   to hold metadat
2ff00 61 20 66 6f 72 20 61 6e 20 53 51 4c 20 66 75 6e  a for an SQL fun
2ff10 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a  ction parameter.
2ff20 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e  **          when
2ff30 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2ff40 61 74 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  at parameter cha
2ff50 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  nges..**.** {H16
2ff60 32 37 38 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74  278} When [sqlit
2ff70 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
2ff80 2c 4e 2c 50 2c 44 29 5d 20 69 73 20 69 6e 76 6f  ,N,P,D)] is invo
2ff90 6b 65 64 2c 20 74 68 65 20 64 65 73 74 72 75 63  ked, the destruc
2ffa0 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tor.**          
2ffb0 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 6e  is called for an
2ffc0 79 20 70 72 69 6f 72 20 6d 65 74 61 64 61 74 61  y prior metadata
2ffd0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2ffe0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2fff0 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  on.**          c
30000 6f 6e 74 65 78 74 20 43 20 61 6e 64 20 70 61 72  ontext C and par
30010 61 6d 65 74 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20  ameter N..**.** 
30020 7b 48 31 36 32 37 39 7d 20 53 51 4c 69 74 65 20  {H16279} SQLite 
30030 77 69 6c 6c 20 63 61 6c 6c 20 64 65 73 74 72 75  will call destru
30040 63 74 6f 72 73 20 66 6f 72 20 61 6e 79 20 6d 65  ctors for any me
30050 74 61 64 61 74 61 20 69 74 20 69 73 20 68 6f 6c  tadata it is hol
30060 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ding.**         
30070 20 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72   in a particular
30080 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30090 6d 65 6e 74 5d 20 53 20 77 68 65 6e 20 65 69 74  ment] S when eit
300a0 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
300b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
300c0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
300d0 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63  inalize(S)] is c
300e0 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  alled..*/.void *
300f0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
30100 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
30110 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
30120 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
30130 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
30140 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
30150 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
30160 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
30170 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
30180 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
30190 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
301a0 20 42 65 68 61 76 69 6f 72 20 7b 48 31 30 32 38   Behavior {H1028
301b0 30 7d 20 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S30100>.**.*
301c0 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
301d0 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
301e0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
301f0 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
30200 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
30210 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
30220 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
30230 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
30240 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73 74 72  ].  If the destr
30250 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
30260 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
30270 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
30280 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
30290 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
302a0 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
302b0 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
302c0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
302d0 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
302e0 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
302f0 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
30300 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
30310 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
30320 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
30330 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
30340 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
30350 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
30360 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
30370 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
30380 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
30390 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
303a0 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
303b0 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
303c0 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
303d0 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
303e0 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b  ilers.  See tick
303f0 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70  et #2191..*/.typ
30400 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
30410 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
30420 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
30430 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
30440 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
30450 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
30460 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
30470 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
30480 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
30490 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
304a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
304b0 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
304c0 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
304d0 74 69 6f 6e 20 7b 48 31 36 34 30 30 7d 20 3c 53  tion {H16400} <S
304e0 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
304f0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
30500 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
30510 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
30520 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
30530 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
30540 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
30550 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
30560 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
30570 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
30580 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
30590 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
305a0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
305b0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
305c0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
305d0 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
305e0 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
305f0 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
30600 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
30610 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
30620 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
30630 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
30640 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30650 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
30660 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
30670 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
30680 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
30690 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
306a0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
306b0 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74  esult_blob() int
306c0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
306d0 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
306e0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
306f0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
30700 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68  o be the BLOB wh
30710 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70  ose content is p
30720 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20  ointed.** to by 
30730 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
30740 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69  eter and which i
30750 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77  s N bytes long w
30760 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
30770 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
30780 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
30790 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
307a0 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73  lob() interfaces
307b0 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
307c0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
307d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
307e0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42  nction to be a B
307f0 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
30800 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73  ll zero.** bytes
30810 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
30820 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73  size, where N is
30830 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
30840 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
30850 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
30860 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
30870 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
30880 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
30890 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
308a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
308b0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f  tion to be a flo
308c0 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
308d0 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
308e0 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  y its 2nd argume
308f0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  nt..**.** The sq
30900 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30910 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
30920 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
30930 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
30940 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
30950 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
30960 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
30970 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69  ception..** SQLi
30980 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
30990 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
309a0 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
309b0 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
309c0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
309d0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
309e0 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
309f0 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
30a00 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
30a10 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65   SQLite interpre
30a20 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ts the error.** 
30a30 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66  message string f
30a40 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
30a50 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54  lt_error() as UT
30a60 46 2d 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69  F-8. SQLite.** i
30a70 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74  nterprets the st
30a80 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
30a90 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
30aa0 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  () as UTF-16 in 
30ab0 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f  native.** byte o
30ac0 72 64 65 72 2e 20 20 49 66 20 74 68 65 20 74 68  rder.  If the th
30ad0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
30ae0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30af0 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
30b00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30b10 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69  or16() is negati
30b20 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
30b30 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f  akes as the erro
30b40 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c  r.** message all
30b50 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68   text up through
30b60 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
30b70 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66  character..** If
30b80 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
30b90 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
30ba0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
30bb0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
30bc0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
30bd0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
30be0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
30bf0 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
30c00 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
30c10 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
30c20 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
30c30 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
30c40 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
30c50 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
30c60 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
30c70 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72  t_error16().** r
30c80 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70  outines make a p
30c90 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
30ca0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
30cb0 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20   text before.** 
30cc0 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65  they return.  He
30cd0 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  nce, the calling
30ce0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65   function can de
30cf0 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d  allocate or.** m
30d00 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61  odify the text a
30d10 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e  fter they return
30d20 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
30d30 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
30d40 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
30d50 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67  ) function chang
30d60 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  es the error cod
30d70 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
30d80 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73   SQLite as a res
30d90 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ult of an error 
30da0 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20  in a function.  
30db0 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
30dc0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
30dd0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
30de0 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
30df0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
30e00 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
30e10 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
30e20 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
30e30 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
30e40 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
30e50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
30e60 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69  te3_result_toobi
30e70 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
30e80 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
30e90 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a  hrow an error.**
30ea0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
30eb0 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
30ec0 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20  B is to long to 
30ed0 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
30ee0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
30ef0 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ult_nomem() inte
30f00 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
30f10 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
30f20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
30f30 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
30f40 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
30f50 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  led..**.** The s
30f60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
30f70 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
30f80 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
30f90 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
30fa0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
30fb0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
30fc0 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
30fd0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
30fe0 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
30ff0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
31000 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
31010 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
31020 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
31030 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
31040 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
31050 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
31060 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
31070 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
31080 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
31090 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
310a0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
310b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
310c0 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  _null() interfac
310d0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
310e0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
310f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
31100 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
31110 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
31120 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
31130 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
31140 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
31150 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  6(),.** sqlite3_
31160 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
31170 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
31180 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
31190 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
311a0 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
311b0 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
311c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
311d0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
311e0 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
311f0 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
31200 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
31210 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
31220 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
31230 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
31240 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
31250 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
31260 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74  ely..** SQLite t
31270 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65  akes the text re
31280 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70  sult from the ap
31290 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a  plication from.*
312a0 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  * the 2nd parame
312b0 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ter of the sqlit
312c0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
312d0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49  interfaces..** I
312e0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
312f0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
31300 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
31310 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
31320 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
31330 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73  SQLite takes res
31340 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68  ult text from th
31350 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  e 2nd parameter.
31360 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  ** through the f
31370 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
31380 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33  ter..** If the 3
31390 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
313a0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
313b0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
313c0 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65  ces.** is non-ne
313d0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20  gative, then as 
313e0 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20  many bytes (not 
313f0 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74  characters) of t
31400 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74  he text.** point
31410 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64  ed to by the 2nd
31420 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74   parameter are t
31430 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c  aken as the appl
31440 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a  ication-defined.
31450 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75  ** function resu
31460 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74  lt..** If the 4t
31470 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
31480 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
31490 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
314a0 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
314b0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
314c0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
314d0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
314e0 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
314f0 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
31500 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
31510 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
31520 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
31530 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
31540 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
31550 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72  * If the 4th par
31560 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
31570 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31580 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72  t* interfaces or
31590 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
315a0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
315b0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
315c0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
315d0 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
315e0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
315f0 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
31600 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
31610 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
31620 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
31630 20 69 74 20 6f 72 20 63 61 6c 6c 20 61 20 64 65   it or call a de
31640 73 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69 74  structor when it
31650 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
31660 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
31670 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70  .** If the 4th p
31680 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
31690 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
316a0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
316b0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
316c0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
316d0 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
316e0 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
316f0 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
31700 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
31710 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
31720 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
31730 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
31740 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
31750 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
31760 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ns..**.** The sq
31770 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
31780 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ue() interface s
31790 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ets the result o
317a0 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
317b0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
317c0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f  ction to be a co
317d0 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f  py the.** [unpro
317e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
317f0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65  alue] object spe
31800 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e  cified by the 2n
31810 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
31820 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
31830 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
31840 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
31850 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
31860 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
31870 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
31880 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
31890 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
318a0 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
318b0 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
318c0 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
318d0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
318e0 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
318f0 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f   harm..** A [pro
31900 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
31910 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79  alue] object may
31920 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20   always be used 
31930 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70  where an.** [unp
31940 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
31950 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69  _value] object i
31960 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65  s required, so e
31970 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66  ither.** kind of
31980 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
31990 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75   object can be u
319a0 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e  sed with this in
319b0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
319c0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
319d0 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
319e0 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66   within the diff
319f0 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20  erent thread.** 
31a00 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e  than the one con
31a10 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c  taining the appl
31a20 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
31a30 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65  function that re
31a40 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73  ceived.** the [s
31a50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
31a60 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73  pointer, the res
31a70 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
31a80 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
31a90 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ANTS:.**.** {H16
31aa0 34 30 33 7d 20 54 68 65 20 64 65 66 61 75 6c 74  403} The default
31ab0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
31ac0 6f 6d 20 61 6e 79 20 53 51 4c 20 66 75 6e 63 74  om any SQL funct
31ad0 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ion is NULL..**.
31ae0 2a 2a 20 7b 48 31 36 34 30 36 7d 20 54 68 65 20  ** {H16406} The 
31af0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
31b00 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  blob(C,V,N,D)] i
31b10 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
31b20 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
31b30 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
31b40 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
31b50 65 20 61 20 42 4c 4f 42 20 74 68 61 74 20 69 73  e a BLOB that is
31b60 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20   N bytes.**     
31b70 20 20 20 20 20 69 6e 20 6c 65 6e 67 74 68 20 61       in length a
31b80 6e 64 20 77 69 74 68 20 63 6f 6e 74 65 6e 74 20  nd with content 
31b90 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2e  pointed to by V.
31ba0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 39 7d 20  .**.** {H16409} 
31bb0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
31bc0 75 6c 74 5f 64 6f 75 62 6c 65 28 43 2c 56 29 5d  ult_double(C,V)]
31bd0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
31be0 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
31bf0 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
31c00 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
31c10 20 62 65 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   be the floating
31c20 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 56 2e 0a   point value V..
31c30 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 32 7d 20 54  **.** {H16412} T
31c40 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
31c50 6c 74 5f 65 72 72 6f 72 28 43 2c 56 2c 4e 29 5d  lt_error(C,V,N)]
31c60 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
31c70 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a  es the return.**
31c80 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
31c90 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
31ca0 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e   be an exception
31cb0 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65   with error code
31cc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
31cd0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20  LITE_ERROR] and 
31ce0 61 20 55 54 46 2d 38 20 65 72 72 6f 72 20 6d 65  a UTF-8 error me
31cf0 73 73 61 67 65 20 63 6f 70 69 65 64 20 66 72 6f  ssage copied fro
31d00 6d 20 56 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  m V up to the.**
31d10 20 20 20 20 20 20 20 20 20 20 66 69 72 73 74 20            first 
31d20 7a 65 72 6f 20 62 79 74 65 20 6f 72 20 75 6e 74  zero byte or unt
31d30 69 6c 20 4e 20 62 79 74 65 73 20 61 72 65 20 72  il N bytes are r
31d40 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69  ead if N is posi
31d50 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  tive..**.** {H16
31d60 34 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  415} The [sqlite
31d70 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
31d80 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61  (C,V,N)] interfa
31d90 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
31da0 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
31db0 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74    value of funct
31dc0 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65  ion C to be an e
31dd0 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72  xception with er
31de0 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20  ror code.**     
31df0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
31e00 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 2d 31 36  OR] and a UTF-16
31e10 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
31e20 65 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  er error message
31e30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 70  .**          cop
31e40 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f  ied from V up to
31e50 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
31e60 74 65 72 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e  terminator or un
31e70 74 69 6c 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20  til N bytes.**  
31e80 20 20 20 20 20 20 20 20 61 72 65 20 72 65 61 64          are read
31e90 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76   if N is positiv
31ea0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 38  e..**.** {H16418
31eb0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
31ec0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
31ed0 69 67 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  ig(C)] interface
31ee0 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
31ef0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
31f00 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e  value of the fun
31f10 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
31f20 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
31f30 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
31f40 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54         [SQLITE_T
31f50 4f 4f 42 49 47 5d 20 61 6e 64 20 61 6e 20 61 70  OOBIG] and an ap
31f60 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20  propriate error 
31f70 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b  message..**.** {
31f80 48 31 36 34 32 31 7d 20 54 68 65 20 5b 73 71 6c  H16421} The [sql
31f90 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31fa0 72 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65  r_nomem(C)] inte
31fb0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
31fc0 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
31fd0 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
31fe0 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  e function C to 
31ff0 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
32000 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a  with error code.
32010 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
32020 49 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61  ITE_NOMEM] and a
32030 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72  n appropriate er
32040 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
32050 2a 2a 20 7b 48 31 36 34 32 34 7d 20 54 68 65 20  ** {H16424} The 
32060 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32070 65 72 72 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d  error_code(C,E)]
32080 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
32090 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a  es the return.**
320a0 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
320b0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
320c0 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70  C to be an excep
320d0 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20  tion with error 
320e0 63 6f 64 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20  code E..**      
320f0 20 20 20 20 54 68 65 20 65 72 72 6f 72 20 6d 65      The error me
32100 73 73 61 67 65 20 74 65 78 74 20 69 73 20 75 6e  ssage text is un
32110 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  changed..**.** {
32120 48 31 36 34 32 37 7d 20 54 68 65 20 5b 73 71 6c  H16427} The [sql
32130 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
32140 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,V)] interface 
32150 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
32160 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
32170 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
32180 20 43 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d   C to be the 32-
32190 62 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75  bit integer valu
321a0 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  e V..**.** {H164
321b0 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  30} The [sqlite3
321c0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c  _result_int64(C,
321d0 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  V)] interface ch
321e0 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
321f0 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
32200 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
32210 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
32220 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20  t integer value 
32230 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 33  V..**.** {H16433
32240 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
32250 65 73 75 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69  esult_null(C)] i
32260 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
32270 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
32280 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
32290 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
322a0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  e NULL..**.** {H
322b0 31 36 34 33 36 7d 20 54 68 65 20 5b 73 71 6c 69  16436} The [sqli
322c0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
322d0 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
322e0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
322f0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
32300 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
32310 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
32320 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
32330 20 20 20 20 20 20 20 20 20 20 56 20 75 70 20 74            V up t
32340 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
32350 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76   if N is negativ
32360 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  e.**          or
32370 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74   the first N byt
32380 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20  es of V if N is 
32390 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a  non-negative..**
323a0 0a 2a 2a 20 7b 48 31 36 34 33 39 7d 20 54 68 65  .** {H16439} The
323b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
323c0 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29  _text16(C,V,N,D)
323d0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
323e0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
323f0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
32400 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
32410 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31 36 20  o be the UTF-16 
32420 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
32430 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  r.**          st
32440 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65  ring V up to the
32450 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
32460 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20   is negative.** 
32470 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
32480 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66  first N bytes of
32490 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e   V if N is non-n
324a0 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
324b0 48 31 36 34 34 32 7d 20 54 68 65 20 5b 73 71 6c  H16442} The [sql
324c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
324d0 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  16be(C,V,N,D)] i
324e0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
324f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
32500 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
32510 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
32520 65 20 74 68 65 20 55 54 46 2d 31 36 20 62 69 67  e the UTF-16 big
32530 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20  -endian.**      
32540 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20      string V up 
32550 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
32560 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69  o if N is negati
32570 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ve.**          o
32580 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79  r the first N by
32590 74 65 73 20 6f 72 20 56 20 69 66 20 4e 20 69 73  tes or V if N is
325a0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
325b0 2a 0a 2a 2a 20 7b 48 31 36 34 34 35 7d 20 54 68  *.** {H16445} Th
325c0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
325d0 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e  t_text16le(C,V,N
325e0 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
325f0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
32600 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
32610 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
32620 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d  C to be the UTF-
32630 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  16 little-endian
32640 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
32650 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20  ing V up to the 
32660 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20  first zero if N 
32670 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20  is negative.**  
32680 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66          or the f
32690 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20  irst N bytes of 
326a0 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  V if N is non-ne
326b0 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  gative..**.** {H
326c0 31 36 34 34 38 7d 20 54 68 65 20 5b 73 71 6c 69  16448} The [sqli
326d0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
326e0 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,V)] interface
326f0 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
32700 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
32710 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
32720 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 5b 75  n C to be the [u
32730 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
32740 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 20 20 20  e3_value].**    
32750 20 20 20 20 20 20 6f 62 6a 65 63 74 20 56 2e 0a        object V..
32760 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 31 7d 20 54  **.** {H16451} T
32770 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
32780 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29  lt_zeroblob(C,N)
32790 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
327a0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
327b0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
327c0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
327d0 6f 20 62 65 20 61 6e 20 4e 2d 62 79 74 65 20 42  o be an N-byte B
327e0 4c 4f 42 20 6f 66 20 61 6c 6c 20 7a 65 72 6f 73  LOB of all zeros
327f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 34 7d  ..**.** {H16454}
32800 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
32810 73 75 6c 74 5f 65 72 72 6f 72 28 29 5d 20 61 6e  sult_error()] an
32820 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
32830 74 5f 65 72 72 6f 72 31 36 28 29 5d 0a 2a 2a 20  t_error16()].** 
32840 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
32850 63 65 73 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  ces make a copy 
32860 6f 66 20 74 68 65 69 72 20 65 72 72 6f 72 20 6d  of their error m
32870 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 62  essage strings b
32880 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20  efore.**        
32890 20 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a    returning..**.
328a0 2a 2a 20 7b 48 31 36 34 35 37 7d 20 49 66 20 74  ** {H16457} If t
328b0 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20  he D destructor 
328c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
328d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
328e0 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  b(C,V,N,D)],.** 
328f0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
32900 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c  3_result_text(C,
32910 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65  V,N,D)], [sqlite
32920 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
32930 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
32940 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
32950 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
32960 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  C,V,N,D)], or.**
32970 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
32980 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
32990 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20  le(C,V,N,D)] is 
329a0 74 68 65 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51  the constant [SQ
329b0 4c 49 54 45 5f 53 54 41 54 49 43 5d 0a 2a 2a 20  LITE_STATIC].** 
329c0 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 6e 6f           then no
329d0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 65   destructor is e
329e0 76 65 72 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68  ver called on th
329f0 65 20 70 6f 69 6e 74 65 72 20 56 20 61 6e 64 20  e pointer V and 
32a00 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20 20  SQLite.**       
32a10 20 20 20 61 73 73 75 6d 65 73 20 74 68 61 74 20     assumes that 
32a20 56 20 69 73 20 69 6d 6d 75 74 61 62 6c 65 2e 0a  V is immutable..
32a30 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 30 7d 20 49  **.** {H16460} I
32a40 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74  f the D destruct
32a50 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  or parameter to 
32a60 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32a70 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a  blob(C,V,N,D)],.
32a80 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
32a90 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32aa0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c  (C,V,N,D)], [sql
32ab0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32ac0 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  16(C,V,N,D)],.**
32ad0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
32ae0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
32af0 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72  be(C,V,N,D)], or
32b00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
32b10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32b20 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16le(C,V,N,D)] 
32b30 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 0a  is the constant.
32b40 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
32b50 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74  ITE_TRANSIENT] t
32b60 68 65 6e 20 74 68 65 20 69 6e 74 65 72 66 61 63  hen the interfac
32b70 65 73 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  es makes a copy 
32b80 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
32b90 20 20 20 63 6f 6e 74 65 6e 74 20 6f 66 20 56 20     content of V 
32ba0 61 6e 64 20 72 65 74 61 69 6e 73 20 74 68 65 20  and retains the 
32bb0 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  copy..**.** {H16
32bc0 34 36 33 7d 20 49 66 20 74 68 65 20 44 20 64 65  463} If the D de
32bd0 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74  structor paramet
32be0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  er to [sqlite3_r
32bf0 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
32c00 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
32c10 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
32c20 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
32c30 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  , [sqlite3_resul
32c40 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
32c50 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
32c60 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32c70 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
32c80 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
32c90 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
32ca0 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
32cb0 4e 2c 44 29 5d 20 69 73 20 73 6f 6d 65 20 76 61  N,D)] is some va
32cc0 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a  lue other than.*
32cd0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63  *          the c
32ce0 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45  onstants [SQLITE
32cf0 5f 53 54 41 54 49 43 5d 20 61 6e 64 20 5b 53 51  _STATIC] and [SQ
32d00 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20  LITE_TRANSIENT] 
32d10 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
32d20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
32d30 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
32d40 6f 72 20 44 20 77 69 74 68 20 56 20 61 73 20 69  or D with V as i
32d50 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  ts only argument
32d60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65  .**          whe
32d70 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
32d80 64 20 77 69 74 68 20 74 68 65 20 56 20 76 61 6c  d with the V val
32d90 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ue..*/.void sqli
32da0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
32db0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32dc0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
32dd0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
32de0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
32df0 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
32e00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32e10 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20  , double);.void 
32e20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32e30 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e  rror(sqlite3_con
32e40 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
32e50 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  r*, int);.void s
32e60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32e70 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ror16(sqlite3_co
32e80 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
32e90 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
32ea0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32eb0 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69  rror_toobig(sqli
32ec0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
32ed0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32ee0 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73  lt_error_nomem(s
32ef0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
32f00 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
32f10 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
32f20 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32f30 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
32f40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
32f50 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32f60 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
32f70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
32f80 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
32f90 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
32fa0 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  64);.void sqlite
32fb0 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71  3_result_null(sq
32fc0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
32fd0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
32fe0 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65  sult_text(sqlite
32ff0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
33000 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f  t char*, int, vo
33010 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
33020 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
33030 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  lt_text16(sqlite
33040 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
33050 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
33060 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
33070 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
33080 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  lt_text16le(sqli
33090 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
330a0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
330b0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
330c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
330d0 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c  ult_text16be(sql
330e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
330f0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
33100 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
33110 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
33120 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74  sult_value(sqlit
33130 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
33140 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f  ite3_value*);.vo
33150 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
33160 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
33170 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
33180 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
33190 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
331a0 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
331b0 6e 63 65 73 20 7b 48 31 36 36 30 30 7d 20 3c 53  nces {H16600} <S
331c0 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20300>.**.** The
331d0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
331e0 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77   used to add new
331f0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
33200 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  nces to the.** [
33210 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33220 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61  ion] specified a
33230 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
33240 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
33250 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20  name of the new 
33260 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
33270 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20  ce is specified 
33280 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  as a UTF-8 strin
33290 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
332a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
332b0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
332c0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
332d0 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
332e0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72  TF-16 string for
332f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33300 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49  collation16(). I
33310 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74  n all cases.** t
33320 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65  he name is passe
33330 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
33340 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
33350 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  t..**.** The thi
33360 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20  rd argument may 
33370 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  be one of the co
33380 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f  nstants [SQLITE_
33390 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  UTF8],.** [SQLIT
333a0 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53  E_UTF16LE] or [S
333b0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20  QLITE_UTF16BE], 
333c0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
333d0 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65  the user-supplie
333e0 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70  d.** routine exp
333f0 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65  ects to be passe
33400 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  d pointers to st
33410 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73  rings encoded us
33420 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54  ing UTF-8,.** UT
33430 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69  F-16 little-endi
33440 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
33450 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g-endian, respec
33460 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74  tively. The.** t
33470 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69  hird argument mi
33480 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c  ght also be [SQL
33490 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
334a0 44 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  D] to indicate t
334b0 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69  hat.** the routi
334c0 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74  ne expects point
334d0 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f  ers to 16-bit wo
334e0 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e  rd aligned strin
334f0 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20  gs.** of UTF-16 
33500 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
33510 74 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te order of the 
33520 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a  host computer..*
33530 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  *.** A pointer t
33540 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c  o the user suppl
33550 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  ied routine must
33560 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
33570 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d  e fifth.** argum
33580 65 6e 74 2e 20 20 49 66 20 69 74 20 69 73 20 4e  ent.  If it is N
33590 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65  ULL, this is the
335a0 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e   same as deletin
335b0 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  g the collation.
335c0 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20  ** sequence (so 
335d0 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e  that SQLite cann
335e0 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f  ot call it anymo
335f0 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d  re)..** Each tim
33600 65 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  e the applicatio
33610 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74  n supplied funct
33620 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ion is invoked, 
33630 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20  it is passed.** 
33640 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72  as its first par
33650 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66  ameter a copy of
33660 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65   the void* passe
33670 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
33680 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
33690 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
336a0 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  llation() or sql
336b0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
336c0 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a  ation16()..**.**
336d0 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61   The remaining a
336e0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
336f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70  application-supp
33700 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65  lied routine are
33710 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a   two strings,.**
33720 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74 65   each represente
33730 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20  d by a (length, 
33740 64 61 74 61 29 20 70 61 69 72 20 61 6e 64 20 65  data) pair and e
33750 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e  ncoded in the en
33760 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77  coding.** that w
33770 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  as passed as the
33780 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
33790 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  when the collati
337a0 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a  on sequence was.
337b0 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20 7b  ** registered. {
337c0 45 4e 44 7d 20 20 54 68 65 20 61 70 70 6c 69 63  END}  The applic
337d0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f  ation defined co
337e0 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20  llation routine 
337f0 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
33800 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20   negative, zero 
33810 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 20 74  or positive if t
33820 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20  he first string 
33830 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a  is less than,.**
33840 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
33850 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
33860 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e  econd string. i.
33870 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54  e. (STRING1 - ST
33880 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  RING2)..**.** Th
33890 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
338a0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
338b0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
338c0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
338d0 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  ion().** except 
338e0 74 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e  that it takes an
338f0 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20   extra argument 
33900 77 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72  which is a destr
33910 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65  uctor for.** the
33920 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65   collation.  The
33930 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
33940 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63  alled when the c
33950 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  ollation is.** d
33960 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20  estroyed and is 
33970 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66  passed a copy of
33980 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
33990 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e  meter void* poin
339a0 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ter.** of the sq
339b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
339c0 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20  lation_v2()..** 
339d0 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64  Collations are d
339e0 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68  estroyed when th
339f0 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65  ey are overridde
33a00 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73  n by later calls
33a10 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61   to the.** colla
33a20 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75  tion creation fu
33a30 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20  nctions or when 
33a40 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
33a50 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f  nnection] is clo
33a60 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  sed.** using [sq
33a70 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
33a80 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
33a90 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 33 7d  :.**.** {H16603}
33aa0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
33ab0 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  ll to the.**    
33ac0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
33ad0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
33ae0 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
33af0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20   interface.**   
33b00 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 73         registers
33b10 20 66 75 6e 63 74 69 6f 6e 20 46 20 61 73 20 74   function F as t
33b20 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75  he comparison fu
33b30 6e 63 74 69 6f 6e 20 75 73 65 64 20 74 6f 0a 2a  nction used to.*
33b40 2a 20 20 20 20 20 20 20 20 20 20 69 6d 70 6c 65  *          imple
33b50 6d 65 6e 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 58  ment collation X
33b60 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
33b70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20  e connection] B 
33b80 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
33b90 64 61 74 61 62 61 73 65 73 20 68 61 76 69 6e 67  databases having
33ba0 20 65 6e 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a   encoding E..**.
33bb0 2a 2a 20 7b 48 31 36 36 30 34 7d 20 53 51 4c 69  ** {H16604} SQLi
33bc0 74 65 20 75 6e 64 65 72 73 74 61 6e 64 73 20 74  te understands t
33bd0 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20 74  he X parameter t
33be0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
33bf0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
33c00 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
33c10 2c 50 2c 46 2c 44 29 5d 20 61 73 20 61 20 7a 65  ,P,F,D)] as a ze
33c20 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
33c30 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20            UTF-8 
33c40 73 74 72 69 6e 67 20 69 6e 20 77 68 69 63 68 20  string in which 
33c50 63 61 73 65 20 69 73 20 69 67 6e 6f 72 65 64 20  case is ignored 
33c60 66 6f 72 20 41 53 43 49 49 20 63 68 61 72 61 63  for ASCII charac
33c70 74 65 72 73 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ters and.**     
33c80 20 20 20 20 20 69 73 20 73 69 67 6e 69 66 69 63       is signific
33c90 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41 53 43 49  ant for non-ASCI
33ca0 49 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  I characters..**
33cb0 0a 2a 2a 20 7b 48 31 36 36 30 36 7d 20 53 75 63  .** {H16606} Suc
33cc0 63 65 73 73 69 76 65 20 63 61 6c 6c 73 20 74 6f  cessive calls to
33cd0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33ce0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
33cf0 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20  X,E,P,F,D)].**  
33d00 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68 65          with the
33d10 20 73 61 6d 65 20 76 61 6c 75 65 73 20 66 6f 72   same values for
33d20 20 42 2c 20 58 2c 20 61 6e 64 20 45 2c 20 6f 76   B, X, and E, ov
33d30 65 72 72 69 64 65 20 70 72 69 6f 72 20 76 61 6c  erride prior val
33d40 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ues.**          
33d50 6f 66 20 50 2c 20 46 2c 20 61 6e 64 20 44 2e 0a  of P, F, and D..
33d60 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 39 7d 20 49  **.** {H16609} I
33d70 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
33d80 20 44 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63   D in [sqlite3_c
33d90 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
33da0 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
33db0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
33dc0 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74  not NULL then it
33dd0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
33de0 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 20  argument P when 
33df0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
33e00 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
33e10 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 62 79  on is dropped by
33e20 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b   SQLite..**.** {
33e30 48 31 36 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74  H16612} A collat
33e40 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
33e50 64 72 6f 70 70 65 64 20 77 68 65 6e 20 69 74 20  dropped when it 
33e60 69 73 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a  is overloaded..*
33e70 2a 0a 2a 2a 20 7b 48 31 36 36 31 35 7d 20 41 20  *.** {H16615} A 
33e80 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
33e90 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68  on is dropped wh
33ea0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
33eb0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20  connection.**   
33ec0 20 20 20 20 20 20 20 69 73 20 63 6c 6f 73 65 64         is closed
33ed0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
33ee0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  close()]..**.** 
33ef0 7b 48 31 36 36 31 38 7d 20 54 68 65 20 70 6f 69  {H16618} The poi
33f00 6e 74 65 72 20 50 20 69 6e 20 5b 73 71 6c 69 74  nter P in [sqlit
33f10 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33f20 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
33f30 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,D)].**         
33f40 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
33f50 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
33f60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
33f70 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20   comparison.**  
33f80 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e          function
33f90 20 46 20 66 6f 72 20 61 6c 6c 20 73 75 62 73 65   F for all subse
33fa0 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
33fb0 73 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 48  s of F..**.** {H
33fc0 31 36 36 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f  16621} A call to
33fd0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33fe0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45  _collation(B,X,E
33ff0 2c 50 2c 46 29 5d 20 69 73 20 65 78 61 63 74 6c  ,P,F)] is exactl
34000 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  y.**          th
34010 65 20 73 61 6d 65 20 61 73 20 61 20 63 61 6c 6c  e same as a call
34020 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
34030 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
34040 28 29 5d 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  ()] with.**     
34050 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 70 61       the same pa
34060 72 61 6d 65 74 65 72 73 20 61 6e 64 20 61 20 4e  rameters and a N
34070 55 4c 4c 20 64 65 73 74 72 75 63 74 6f 72 2e 0a  ULL destructor..
34080 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 34 7d 20 46  **.** {H16624} F
34090 6f 6c 6c 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69  ollowing a [sqli
340a0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
340b0 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
340c0 46 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  F,D)],.**       
340d0 20 20 20 53 51 4c 69 74 65 20 75 73 65 73 20 74     SQLite uses t
340e0 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75  he comparison fu
340f0 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c  nction F for all
34100 20 74 65 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e   text comparison
34110 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70 65  .**          ope
34120 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 5b  rations on the [
34130 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
34140 69 6f 6e 5d 20 42 20 6f 6e 20 74 65 78 74 20 76  ion] B on text v
34150 61 6c 75 65 73 20 74 68 61 74 0a 2a 2a 20 20 20  alues that.**   
34160 20 20 20 20 20 20 20 75 73 65 20 74 68 65 20 63         use the c
34170 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63  ollating sequenc
34180 65 20 6e 61 6d 65 64 20 58 2e 0a 2a 2a 0a 2a 2a  e named X..**.**
34190 20 7b 48 31 36 36 32 37 7d 20 54 68 65 20 5b 73   {H16627} The [s
341a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
341b0 6c 6c 61 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c  llation16(B,X,E,
341c0 50 2c 46 29 5d 20 77 6f 72 6b 73 20 74 68 65 20  P,F)] works the 
341d0 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
341e0 20 61 73 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   as [sqlite3_cre
341f0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c  ate_collation(B,
34200 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63 65 70 74  X,E,P,F)] except
34210 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20   that the.**    
34220 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20        collation 
34230 6e 61 6d 65 20 58 20 69 73 20 75 6e 64 65 72 73  name X is unders
34240 74 6f 6f 64 20 61 73 20 55 54 46 2d 31 36 20 69  tood as UTF-16 i
34250 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
34260 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
34270 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38  instead of UTF-8
34280 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 33 30 7d  ..**.** {H16630}
34290 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63   When multiple c
342a0 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69  omparison functi
342b0 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ons are availabl
342c0 65 20 66 6f 72 20 74 68 65 20 73 61 6d 65 0a 2a  e for the same.*
342d0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
342e0 74 69 6e 67 20 73 65 71 75 65 6e 63 65 2c 20 53  ting sequence, S
342f0 51 4c 69 74 65 20 63 68 6f 6f 73 65 73 20 74 68  QLite chooses th
34300 65 20 6f 6e 65 20 77 68 6f 73 65 20 74 65 78 74  e one whose text
34310 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 20 20 20   encoding.**    
34320 20 20 20 20 20 20 72 65 71 75 69 72 65 73 20 74        requires t
34330 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
34340 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72  of conversion fr
34350 6f 6d 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  om the default.*
34360 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20  *          text 
34370 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20  encoding of the 
34380 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74  database..*/.int
34390 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
343a0 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c  collation(.  sql
343b0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
343c0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
343d0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
343e0 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
343f0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
34400 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
34410 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
34420 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
34430 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
34440 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  v2(.  sqlite3*, 
34450 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
34460 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
34470 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
34480 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
34490 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
344a0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
344b0 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
344c0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
344d0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
344e0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
344f0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
34500 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  , .  const void 
34510 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54  *zName,.  int eT
34520 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a  extRep, .  void*
34530 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
34540 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
34550 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
34560 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
34570 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
34580 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43  llation Needed C
34590 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36 37 30 30  allbacks {H16700
345a0 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20300>.**.**
345b0 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67   To avoid having
345c0 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c   to register all
345d0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
345e0 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61  nces before a da
345f0 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65  tabase.** can be
34600 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20   used, a single 
34610 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
34620 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
34630 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  red with the.** 
34640 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
34650 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c  tion] to be call
34660 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75  ed whenever an u
34670 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
34680 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69  on.** sequence i
34690 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  s required..**.*
346a0 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f  * If the functio
346b0 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  n is registered 
346c0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
346d0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
346e0 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65  ed() API,.** the
346f0 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74  n it is passed t
34700 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65  he names of unde
34710 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
34720 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72  sequences as str
34730 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20  ings.** encoded 
34740 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31 36 37 30  in UTF-8. {H1670
34750 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  3} If sqlite3_co
34760 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
34770 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74  () is used,.** t
34780 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73  he names are pas
34790 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  sed as UTF-16 in
347a0 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20   machine native 
347b0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41  byte order..** A
347c0 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
347d0 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65  function replace
347e0 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63  s any existing c
347f0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57  allback..**.** W
34800 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
34810 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65   is invoked, the
34820 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
34830 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79  passed is a copy
34840 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  .** of the secon
34850 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
34860 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
34870 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73  needed() or.** 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 31 36 28 29 2e 20 20 54 68  _needed16().  Th
348a0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
348b0 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  t is the databas
348c0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
348d0 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
348e0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
348f0 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53  SQLITE_UTF8], [S
34900 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a  QLITE_UTF16BE],.
34910 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ** or [SQLITE_UT
34920 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69  F16LE], indicati
34930 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69  ng the most desi
34940 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68  rable form of th
34950 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  e collation.** s
34960 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e  equence function
34970 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20   required.  The 
34980 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
34990 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
349a0 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20  the.** required 
349b0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
349c0 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  ce..**.** The ca
349d0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
349e0 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20  should register 
349f0 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c  the desired coll
34a00 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
34a10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
34a20 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  ollation()], [sq
34a30 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34a40 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  lation16()], or.
34a50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
34a60 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
34a70 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
34a80 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ANTS:.**.** {H16
34a90 37 30 32 7d 20 41 20 73 75 63 63 65 73 73 66 75  702} A successfu
34aa0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
34ab0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
34ac0 64 65 64 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20  ded(D,P,F)].**  
34ad0 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
34ae0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
34af0 65 64 65 64 31 36 28 44 2c 50 2c 46 29 5d 20 63  eded16(D,P,F)] c
34b00 61 75 73 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  auses.**        
34b10 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20    the [database 
34b20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f  connection] D to
34b30 20 69 6e 76 6f 6b 65 20 63 61 6c 6c 62 61 63 6b   invoke callback
34b40 20 46 20 77 69 74 68 20 66 69 72 73 74 0a 2a 2a   F with first.**
34b50 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65            parame
34b60 74 65 72 20 50 20 77 68 65 6e 65 76 65 72 20 69  ter P whenever i
34b70 74 20 6e 65 65 64 73 20 61 20 63 6f 6d 70 61 72  t needs a compar
34b80 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 66 6f  ison function fo
34b90 72 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r a.**          
34ba0 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e  collating sequen
34bb0 63 65 20 74 68 61 74 20 69 74 20 64 6f 65 73 20  ce that it does 
34bc0 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a  not know about..
34bd0 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 34 7d 20 45  **.** {H16704} E
34be0 61 63 68 20 73 75 63 63 65 73 73 66 75 6c 20 63  ach successful c
34bf0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
34c00 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
34c10 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ()] or.**       
34c20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c     [sqlite3_coll
34c30 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
34c40 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 20  ] overrides the 
34c50 63 61 6c 6c 62 61 63 6b 20 72 65 67 69 73 74 65  callback registe
34c60 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
34c70 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
34c80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34c90 5d 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73  ] by prior calls
34ca0 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 20 20   to either.**   
34cb0 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
34cc0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 36 7d  ..**.** {H16706}
34cd0 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   The name of the
34ce0 20 72 65 71 75 65 73 74 65 64 20 63 6f 6c 6c 61   requested colla
34cf0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ting function pa
34d00 73 73 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 20  ssed in the.**  
34d10 20 20 20 20 20 20 20 20 34 74 68 20 70 61 72 61          4th para
34d20 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
34d30 6c 62 61 63 6b 20 69 73 20 69 6e 20 55 54 46 2d  lback is in UTF-
34d40 38 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63  8 if the callbac
34d50 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 61  k.**          wa
34d60 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
34d70 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ng [sqlite3_coll
34d80 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
34d90 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
34da0 69 73 20 69 6e 20 55 54 46 2d 31 36 20 6e 61 74  is in UTF-16 nat
34db0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
34dc0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77  f the callback w
34dd0 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  as.**          r
34de0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
34df0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
34e00 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
34e10 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
34e20 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
34e30 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
34e40 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  void*, .  void(*
34e50 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
34e60 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
34e70 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e  nst char*).);.in
34e80 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
34e90 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20  ion_needed16(.  
34ea0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
34eb0 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  d*,.  void(*)(vo
34ec0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
34ed0 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
34ee0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
34ef0 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
34f00 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
34f10 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
34f20 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
34f30 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
34f40 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
34f50 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
34f60 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
34f70 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
34f80 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
34f90 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
34fa0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
34fb0 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
34fc0 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  e3_key(.  sqlite
34fd0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
34fe0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
34ff0 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
35000 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
35010 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
35020 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
35030 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
35040 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e  hange the key on
35050 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
35060 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65  e.  If the curre
35070 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  nt database is n
35080 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c  ot.** encrypted,
35090 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
350a0 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20  ll encrypt it.  
350b0 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e  If pNew==0 or nN
350c0 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61  ew==0, the.** da
350d0 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70  tabase is decryp
350e0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ted..**.** The c
350f0 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
35100 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
35110 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
35120 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
35130 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
35140 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
35150 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
35160 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
35170 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
35180 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
35190 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
351a0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
351b0 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
351c0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
351d0 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e  CAPI3REF: Suspen
351e0 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20  d Execution For 
351f0 41 20 53 68 6f 72 74 20 54 69 6d 65 20 7b 48 31  A Short Time {H1
35200 30 35 33 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a  0530} <S40410>.*
35210 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
35220 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
35230 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72  n causes the cur
35240 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73  rent thread to s
35250 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
35260 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74  .** for at least
35270 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c   a number of mil
35280 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66  liseconds specif
35290 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d  ied in its param
352a0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  eter..**.** If t
352b0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
352c0 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70  tem does not sup
352d0 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65  port sleep reque
352e0 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c  sts with.** mill
352f0 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73  isecond time res
35300 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  olution, then th
35310 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72  e time will be r
35320 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20  ounded up to.** 
35330 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f  the nearest seco
35340 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  nd. The number o
35350 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  f milliseconds o
35360 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
35370 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
35380 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
35390 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
353a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ned..**.** SQLit
353b0 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69  e implements thi
353c0 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63  s interface by c
353d0 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65  alling the xSlee
353e0 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  p().** method of
353f0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
35400 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
35410 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  t..**.** INVARIA
35420 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35  NTS:.**.** {H105
35430 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  33} The [sqlite3
35440 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72  _sleep(M)] inter
35450 66 61 63 65 20 69 6e 76 6f 6b 65 73 20 74 68 65  face invokes the
35460 20 78 53 6c 65 65 70 0a 2a 2a 20 20 20 20 20 20   xSleep.**      
35470 20 20 20 20 6d 65 74 68 6f 64 20 6f 66 20 74 68      method of th
35480 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
35490 65 33 5f 76 66 73 7c 56 46 53 5d 20 69 6e 20 6f  e3_vfs|VFS] in o
354a0 72 64 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  rder to.**      
354b0 20 20 20 20 73 75 73 70 65 6e 64 20 65 78 65 63      suspend exec
354c0 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72  ution of the cur
354d0 72 65 6e 74 20 74 68 72 65 61 64 20 66 6f 72 20  rent thread for 
354e0 61 74 20 6c 65 61 73 74 0a 2a 2a 20 20 20 20 20  at least.**     
354f0 20 20 20 20 20 4d 20 6d 69 6c 6c 69 73 65 63 6f       M milliseco
35500 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35  nds..**.** {H105
35510 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  36} The [sqlite3
35520 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72  _sleep(M)] inter
35530 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
35540 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20   number of.**   
35550 20 20 20 20 20 20 20 6d 69 6c 6c 69 73 65 63 6f         milliseco
35560 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74  nds of sleep act
35570 75 61 6c 6c 79 20 72 65 71 75 65 73 74 65 64 20  ually requested 
35580 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  of the operating
35590 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 79 73  .**          sys
355a0 74 65 6d 2c 20 77 68 69 63 68 20 6d 69 67 68 74  tem, which might
355b0 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
355c0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4d 2e  the parameter M.
355d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
355e0 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
355f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
35600 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
35610 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
35620 79 20 46 69 6c 65 73 20 7b 48 31 30 33 31 30 7d  y Files {H10310}
35630 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20000>.**.** 
35640 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
35650 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
35660 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
35670 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
35680 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
35690 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
356a0 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
356b0 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
356c0 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
356d0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
356e0 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64  placed in that d
356f0 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68  irectory.  If th
35700 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
35710 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
35720 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65  , then SQLite pe
35730 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20  rforms a search 
35740 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61  for an appropria
35750 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
35760 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a  file directory..
35770 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  **.** It is not 
35780 73 61 66 65 20 74 6f 20 6d 6f 64 69 66 79 20 74  safe to modify t
35790 68 69 73 20 76 61 72 69 61 62 6c 65 20 6f 6e 63  his variable onc
357a0 65 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  e a [database co
357b0 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 68 61 73  nnection].** has
357c0 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 20 49   been opened.  I
357d0 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68  t is intended th
357e0 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
357f0 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20   be set once.** 
35800 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65  as part of proce
35810 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
35820 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79  n and before any
35830 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
35840 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61  e.** routines ha
35850 76 65 20 62 65 65 6e 20 63 61 6c 6c 20 61 6e 64  ve been call and
35860 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
35870 64 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2f  d thereafter..*/
35880 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
35890 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d  har *sqlite3_tem
358a0 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  p_directory;../*
358b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
358c0 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d  st For Auto-Comm
358d0 69 74 20 4d 6f 64 65 20 7b 48 31 32 39 33 30 7d  it Mode {H12930}
358e0 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 4b 45 59   <S60200>.** KEY
358f0 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d  WORDS: {autocomm
35900 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54  it mode}.**.** T
35910 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
35920 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65  utocommit() inte
35930 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f  rface returns no
35940 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72  n-zero or.** zer
35950 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64  o if the given d
35960 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35970 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20  on is or is not 
35980 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  in autocommit mo
35990 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  de,.** respectiv
359a0 65 6c 79 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74  ely.  Autocommit
359b0 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64   mode is on by d
359c0 65 66 61 75 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63  efault..** Autoc
359d0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69  ommit mode is di
359e0 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47  sabled by a [BEG
359f0 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  IN] statement..*
35a00 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  * Autocommit mod
35a10 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20  e is re-enabled 
35a20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72  by a [COMMIT] or
35a30 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a   [ROLLBACK]..**.
35a40 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69  ** If certain ki
35a50 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63  nds of errors oc
35a60 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65  cur on a stateme
35a70 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74  nt within a mult
35a80 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  i-statement.** t
35a90 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f  ransaction (erro
35aa0 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51  rs including [SQ
35ab0 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_FULL], [SQL
35ac0 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b  ITE_IOERR],.** [
35ad0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b  SQLITE_NOMEM], [
35ae0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e  SQLITE_BUSY], an
35af0 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  d [SQLITE_INTERR
35b00 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a  UPT]) then the.*
35b10 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69  * transaction mi
35b20 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ght be rolled ba
35b30 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
35b40 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20  .  The only way 
35b50 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77  to.** find out w
35b60 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75  hether SQLite au
35b70 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
35b80 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ed back the tran
35b90 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a  saction after.**
35ba0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20   an error is to 
35bb0 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f  use this functio
35bc0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  n..**.** INVARIA
35bd0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  NTS:.**.** {H129
35be0 33 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  31} The [sqlite3
35bf0 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
35c00 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  D)] interface re
35c10 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f  turns non-zero o
35c20 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  r.**          ze
35c30 72 6f 20 69 66 20 74 68 65 20 5b 64 61 74 61 62  ro if the [datab
35c40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
35c50 44 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69  D is or is not i
35c60 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20  n autocommit.** 
35c70 20 20 20 20 20 20 20 20 20 6d 6f 64 65 2c 20 72           mode, r
35c80 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
35c90 2a 2a 20 7b 48 31 32 39 33 32 7d 20 41 75 74 6f  ** {H12932} Auto
35ca0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f  commit mode is o
35cb0 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  n by default..**
35cc0 0a 2a 2a 20 7b 48 31 32 39 33 33 7d 20 41 75 74  .** {H12933} Aut
35cd0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
35ce0 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 73 75  disabled by a su
35cf0 63 63 65 73 73 66 75 6c 20 5b 42 45 47 49 4e 5d  ccessful [BEGIN]
35d00 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
35d10 2a 20 7b 48 31 32 39 33 34 7d 20 41 75 74 6f 63  * {H12934} Autoc
35d20 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 65 6e  ommit mode is en
35d30 61 62 6c 65 64 20 62 79 20 61 20 73 75 63 63 65  abled by a succe
35d40 73 73 66 75 6c 20 5b 43 4f 4d 4d 49 54 5d 20 6f  ssful [COMMIT] o
35d50 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a 2a 2a 20  r [ROLLBACK].** 
35d60 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65           stateme
35d70 6e 74 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50  nt..**.** ASSUMP
35d80 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
35d90 32 39 33 36 7d 20 49 66 20 61 6e 6f 74 68 65 72  2936} If another
35da0 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20   thread changes 
35db0 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73  the autocommit s
35dc0 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74  tatus of the dat
35dd0 61 62 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20  abase.**        
35de0 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69    connection whi
35df0 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  le this routine 
35e00 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e  is running, then
35e10 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
35e20 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  e.**          is
35e30 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69   undefined..*/.i
35e40 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  nt sqlite3_get_a
35e50 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65  utocommit(sqlite
35e60 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
35e70 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44  3REF: Find The D
35e80 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f  atabase Handle O
35e90 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
35ea0 74 65 6d 65 6e 74 20 7b 48 31 33 31 32 30 7d 20  tement {H13120} 
35eb0 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60600>.**.** T
35ec0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
35ed0 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72  ndle interface r
35ee0 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61  eturns the [data
35ef0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35f00 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68   handle.** to wh
35f10 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20  ich a [prepared 
35f20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e  statement] belon
35f30 67 73 2e 20 20 54 68 65 20 64 61 74 61 62 61 73  gs.  The databas
35f40 65 20 68 61 6e 64 6c 65 20 72 65 74 75 72 6e 65  e handle returne
35f50 64 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d by.** sqlite3_
35f60 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65  db_handle is the
35f70 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 68   same database h
35f80 61 6e 64 6c 65 20 74 68 61 74 20 77 61 73 20 74  andle that was t
35f90 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
35fa0 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  t.** to the [sql
35fb0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
35fc0 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20  )] call (or its 
35fd0 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77  variants) that w
35fe0 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72  as used to.** cr
35ff0 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  eate the stateme
36000 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  nt in the first 
36010 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  place..**.** INV
36020 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
36030 48 31 33 31 32 33 7d 20 54 68 65 20 5b 73 71 6c  H13123} The [sql
36040 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 53  ite3_db_handle(S
36050 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
36060 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  urns a pointer.*
36070 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74 68  *          to th
36080 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
36090 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74  ection] associat
360a0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 20  ed with the.**  
360b0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
360c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
360d0 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
360e0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71  te3_db_handle(sq
360f0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
36100 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
36110 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65  ind the next pre
36120 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
36130 7b 48 31 33 31 34 30 7d 20 3c 53 36 30 36 30 30  {H13140} <S60600
36140 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  >.**.** This int
36150 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
36160 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
36170 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73  next [prepared s
36180 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a  tatement] after.
36190 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61  ** pStmt associa
361a0 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61  ted with the [da
361b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
361c0 6e 5d 20 70 44 62 2e 20 20 49 66 20 70 53 74 6d  n] pDb.  If pStm
361d0 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65  t is NULL.** the
361e0 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  n this interface
361f0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
36200 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  er to the first 
36210 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
36220 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  nt.** associated
36230 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61   with the databa
36240 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44  se connection pD
36250 62 2e 20 20 49 66 20 6e 6f 20 70 72 65 70 61 72  b.  If no prepar
36260 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
36270 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f  satisfies the co
36280 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73  nditions of this
36290 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74   routine, it ret
362a0 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  urns NULL..**.**
362b0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
362c0 2a 2a 20 7b 48 31 33 31 34 33 7d 20 49 66 20 44  ** {H13143} If D
362d0 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
362e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
362f0 20 68 6f 6c 64 73 20 6f 6e 65 20 6f 72 20 6d 6f   holds one or mo
36300 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75  re.**          u
36310 6e 66 69 6e 61 6c 69 7a 65 64 20 5b 70 72 65 70  nfinalized [prep
36320 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
36330 20 61 6e 64 20 53 20 69 73 20 61 20 4e 55 4c 4c   and S is a NULL
36340 20 70 6f 69 6e 74 65 72 2c 0a 2a 2a 20 20 20 20   pointer,.**    
36350 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69        then [sqli
36360 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c  te3_next_stmt(D,
36370 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61   S)] routine sha
36380 6c 6c 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e  ll return a poin
36390 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ter.**          
363a0 74 6f 20 6f 6e 65 20 6f 66 20 74 68 65 20 70 72  to one of the pr
363b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
363c0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
363d0 68 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31  h D..**.** {H131
363e0 34 36 7d 20 49 66 20 44 20 69 73 20 61 20 5b 64  46} If D is a [d
363f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36400 6f 6e 5d 20 74 68 61 74 20 68 6f 6c 64 73 20 6e  on] that holds n
36410 6f 20 75 6e 66 69 6e 61 6c 69 7a 65 64 0a 2a 2a  o unfinalized.**
36420 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
36430 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
36440 61 6e 64 20 53 20 69 73 20 61 20 4e 55 4c 4c 20  and S is a NULL 
36450 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 0a 2a 2a  pointer, then.**
36460 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
36470 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20  e3_next_stmt(D, 
36480 53 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c  S)] routine shal
36490 6c 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20  l return a NULL 
364a0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  pointer..**.** {
364b0 48 31 33 31 34 39 7d 20 49 66 20 53 20 69 73 20  H13149} If S is 
364c0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
364d0 65 6d 65 6e 74 5d 20 69 6e 20 74 68 65 20 5b 64  ement] in the [d
364e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
364f0 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20  on] D.**        
36500 20 20 61 6e 64 20 53 20 69 73 20 6e 6f 74 20 74    and S is not t
36510 68 65 20 6c 61 73 74 20 70 72 65 70 61 72 65 64  he last prepared
36520 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 44 2c   statement in D,
36530 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
36540 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f    [sqlite3_next_
36550 73 74 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74  stmt(D, S)] rout
36560 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  ine shall return
36570 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20   a pointer.**   
36580 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 6e 65         to the ne
36590 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  xt prepared stat
365a0 65 6d 65 6e 74 20 69 6e 20 44 20 61 66 74 65 72  ement in D after
365b0 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 35   S..**.** {H1315
365c0 32 7d 20 49 66 20 53 20 69 73 20 74 68 65 20 6c  2} If S is the l
365d0 61 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  ast [prepared st
365e0 61 74 65 6d 65 6e 74 5d 20 69 6e 20 74 68 65 0a  atement] in the.
365f0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
36600 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36610 5d 20 44 20 74 68 65 6e 20 74 68 65 20 5b 73 71  ] D then the [sq
36620 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
36630 44 2c 20 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20  D, S)].**       
36640 20 20 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c     routine shall
36650 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70   return a NULL p
36660 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 53  ointer..**.** AS
36670 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
36680 20 7b 41 31 33 31 35 34 7d 20 54 68 65 20 5b 64   {A13154} The [d
36690 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
366a0 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e  on] pointer D in
366b0 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20   a call to.**   
366c0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
366d0 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20  next_stmt(D,S)] 
366e0 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e  must refer to an
366f0 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a   open database.*
36700 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 6e 65  *          conne
36710 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72  ction and in par
36720 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74  ticular must not
36730 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
36740 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73  er..*/.sqlite3_s
36750 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78  tmt *sqlite3_nex
36760 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a  t_stmt(sqlite3 *
36770 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  pDb, sqlite3_stm
36780 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
36790 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d  * CAPI3REF: Comm
367a0 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20  it And Rollback 
367b0 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c  Notification Cal
367c0 6c 62 61 63 6b 73 20 7b 48 31 32 39 35 30 7d 20  lbacks {H12950} 
367d0 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S60400>.**.** T
367e0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  he sqlite3_commi
367f0 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  t_hook() interfa
36800 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
36810 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
36820 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
36830 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
36840 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d  nsaction is comm
36850 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61  itted..** Any ca
36860 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
36870 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
36880 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
36890 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
368a0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
368b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
368c0 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65  erridden..** The
368d0 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
368e0 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  k_hook() interfa
368f0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
36900 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
36910 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
36920 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
36930 6e 73 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d  nsaction is comm
36940 69 74 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61  itted..** Any ca
36950 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
36960 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
36970 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
36980 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
36990 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
369a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
369b0 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65  erridden..** The
369c0 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69   pArg argument i
369d0 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
369e0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
369f0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c  ..** If the call
36a00 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74  back on a commit
36a10 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72   hook function r
36a20 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
36a30 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d  .** then the com
36a40 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64  mit is converted
36a50 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b   into a rollback
36a60 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
36a70 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20  er function was 
36a80 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
36a90 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41  tered, its.** pA
36aa0 72 67 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  rg value is retu
36ab0 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
36ac0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
36ad0 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  d..**.** Registe
36ae0 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63  ring a NULL func
36af0 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68  tion disables th
36b00 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  e callback..**.*
36b10 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73  * For the purpos
36b20 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20  es of this API, 
36b30 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
36b40 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65   said to have be
36b50 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63  en.** rolled bac
36b60 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74  k if an explicit
36b70 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74   "ROLLBACK" stat
36b80 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65  ement is execute
36b90 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  d, or.** an erro
36ba0 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20  r or constraint 
36bb0 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63  causes an implic
36bc0 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f  it rollback to o
36bd0 63 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c  ccur..** The rol
36be0 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69  lback callback i
36bf0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66  s not invoked if
36c00 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
36c10 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
36c20 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ly rolled back b
36c30 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62  ecause the datab
36c40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
36c50 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65  s closed..** The
36c60 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61   rollback callba
36c70 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ck is not invoke
36c80 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69  d if a transacti
36c90 6f 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20  on is.** rolled 
36ca0 62 61 63 6b 20 62 65 63 61 75 73 65 20 61 20 63  back because a c
36cb0 6f 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72  ommit callback r
36cc0 65 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f  eturned non-zero
36cd0 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63  ..** <todo> Chec
36ce0 6b 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f  k on this </todo
36cf0 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  >.**.** INVARIAN
36d00 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35  TS:.**.** {H1295
36d10 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
36d20 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c  commit_hook(D,F,
36d30 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  P)] interface re
36d40 67 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20  gisters the.**  
36d50 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b          callback
36d60 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62   function F to b
36d70 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  e invoked with a
36d80 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76  rgument P whenev
36d90 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  er.**          a
36da0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d   transaction com
36db0 6d 69 74 73 20 6f 6e 20 74 68 65 20 5b 64 61 74  mits on the [dat
36dc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36dd0 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ] D..**.** {H129
36de0 35 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  52} The [sqlite3
36df0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46  _commit_hook(D,F
36e00 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,P)] interface r
36e10 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67  eturns the P arg
36e20 75 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  ument.**        
36e30 20 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69    from the previ
36e40 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20 74 68  ous call with th
36e50 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
36e60 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a   connection] D,.
36e70 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e  **          or N
36e80 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ULL on the first
36e90 20 63 61 6c 6c 20 66 6f 72 20 61 20 70 61 72 74   call for a part
36ea0 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 20  icular database 
36eb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a  connection D..**
36ec0 0a 2a 2a 20 7b 48 31 32 39 35 33 7d 20 45 61 63  .** {H12953} Eac
36ed0 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
36ee0 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
36ef0 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65  ] overwrites the
36f00 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
36f10 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64        registered
36f20 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e   by prior calls.
36f30 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 34 7d 20  .**.** {H12954} 
36f40 49 66 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e  If the F argumen
36f50 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
36f60 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  mmit_hook(D,F,P)
36f70 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20  ] is NULL.**    
36f80 20 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 63        then the c
36f90 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62  ommit hook callb
36fa0 61 63 6b 20 69 73 20 63 61 6e 63 65 6c 65 64 20  ack is canceled 
36fb0 61 6e 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a  and no callback.
36fc0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69  **          is i
36fd0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 74 72  nvoked when a tr
36fe0 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74  ansaction commit
36ff0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 35  s..**.** {H12955
37000 7d 20 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20  } If the commit 
37010 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
37020 20 6e 6f 6e 2d 7a 65 72 6f 20 74 68 65 6e 20 74   non-zero then t
37030 68 65 20 63 6f 6d 6d 69 74 20 69 73 0a 2a 2a 20  he commit is.** 
37040 20 20 20 20 20 20 20 20 20 63 6f 6e 76 65 72 74           convert
37050 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61  ed into a rollba
37060 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36  ck..**.** {H1296
37070 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
37080 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c  rollback_hook(D,
37090 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,P)] interface 
370a0 72 65 67 69 73 74 65 72 73 20 74 68 65 0a 2a 2a  registers the.**
370b0 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
370c0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f  ck function F to
370d0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
370e0 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e   argument P when
370f0 65 76 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ever.**         
37100 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72   a transaction r
37110 6f 6c 6c 73 20 62 61 63 6b 20 6f 6e 20 74 68 65  olls back on the
37120 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37130 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20  ction] D..**.** 
37140 7b 48 31 32 39 36 32 7d 20 54 68 65 20 5b 73 71  {H12962} The [sq
37150 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
37160 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65  ook(D,F,P)] inte
37170 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
37180 65 20 50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  e P.**          
37190 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68  argument from th
371a0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
371b0 77 69 74 68 20 74 68 65 20 73 61 6d 65 0a 2a 2a  with the same.**
371c0 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
371d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
371e0 44 2c 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68  D, or NULL on th
371f0 65 20 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a 20  e first call.** 
37200 20 20 20 20 20 20 20 20 20 66 6f 72 20 61 20 70           for a p
37210 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
37220 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
37230 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 33 7d 20  .**.** {H12963} 
37240 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  Each call to [sq
37250 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
37260 6f 6f 6b 28 29 5d 20 6f 76 65 72 77 72 69 74 65  ook()] overwrite
37270 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
37280 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73  *          regis
37290 74 65 72 65 64 20 62 79 20 70 72 69 6f 72 20 63  tered by prior c
372a0 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  alls..**.** {H12
372b0 39 36 34 7d 20 49 66 20 74 68 65 20 46 20 61 72  964} If the F ar
372c0 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
372d0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
372e0 28 44 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c  (D,F,P)] is NULL
372f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
37300 6e 20 74 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68  n the rollback h
37310 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ook callback is 
37320 63 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20  canceled and no 
37330 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
37340 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20       is invoked 
37350 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63 74 69  when a transacti
37360 6f 6e 20 72 6f 6c 6c 73 20 62 61 63 6b 2e 0a 2a  on rolls back..*
37370 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
37380 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69  commit_hook(sqli
37390 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
373a0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69  d*), void*);.voi
373b0 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  d *sqlite3_rollb
373c0 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  ack_hook(sqlite3
373d0 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20  *, void(*)(void 
373e0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
373f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
37400 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63  a Change Notific
37410 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20  ation Callbacks 
37420 7b 48 31 32 39 37 30 7d 20 3c 53 36 30 34 30 30  {H12970} <S60400
37430 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
37440 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
37450 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
37460 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
37470 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74   function.** wit
37480 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
37490 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e  connection] iden
374a0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  tified by the fi
374b0 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
374c0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
374d0 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20  enever a row is 
374e0 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
374f0 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
37500 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65   Any callback se
37510 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
37520 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e  call to this fun
37530 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65  ction.** for the
37540 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
37550 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
37560 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rridden..**.** T
37570 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
37580 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
37590 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  to the function 
375a0 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61  to invoke when a
375b0 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74  .** row is updat
375c0 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20  ed, inserted or 
375d0 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 54 68 65 20  deleted..** The 
375e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
375f0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
37600 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
37610 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
37620 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64  * to sqlite3_upd
37630 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54  ate_hook()..** T
37640 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61  he second callba
37650 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  ck argument is o
37660 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
37670 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44  SERT], [SQLITE_D
37680 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  ELETE],.** or [S
37690 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64  QLITE_UPDATE], d
376a0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
376b0 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63  operation that c
376c0 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61  aused the callba
376d0 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f  ck.** to be invo
376e0 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72  ked..** The thir
376f0 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67  d and fourth arg
37700 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61  uments to the ca
37710 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70  llback contain p
37720 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a  ointers to the.*
37730 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74  * database and t
37740 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69  able name contai
37750 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63 74 65  ning the affecte
37760 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 69  d row..** The fi
37770 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72  nal callback par
37780 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 72 6f  ameter is the ro
37790 77 69 64 20 6f 66 20 74 68 65 20 72 6f 77 2e 20  wid of the row. 
377a0 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 0a 2a  In the case of.*
377b0 2a 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69  * an update, thi
377c0 73 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 61  s is the rowid a
377d0 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20  fter the update 
377e0 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a  takes place..**.
377f0 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f  ** The update ho
37800 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ok is not invoke
37810 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20  d when internal 
37820 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72  system tables ar
37830 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69  e.** modified (i
37840 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65  .e. sqlite_maste
37850 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
37860 75 65 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  uence)..**.** If
37870 20 61 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f   another functio
37880 6e 20 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79  n was previously
37890 20 72 65 67 69 73 74 65 72 65 64 2c 20 69 74 73   registered, its
378a0 20 70 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69   pArg value.** i
378b0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
378c0 65 72 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72  erwise NULL is r
378d0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  eturned..**.** I
378e0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
378f0 20 7b 48 31 32 39 37 31 7d 20 54 68 65 20 5b 73   {H12971} The [s
37900 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
37910 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72  ok(D,F,P)] inter
37920 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20  face causes the 
37930 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20  callback.**     
37940 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20       function F 
37950 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  to be invoked wi
37960 74 68 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  th first paramet
37970 65 72 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a  er P whenever.**
37980 20 20 20 20 20 20 20 20 20 20 61 20 74 61 62 6c            a tabl
37990 65 20 72 6f 77 20 69 73 20 6d 6f 64 69 66 69 65  e row is modifie
379a0 64 2c 20 69 6e 73 65 72 74 65 64 2c 20 6f 72 20  d, inserted, or 
379b0 64 65 6c 65 74 65 64 20 6f 6e 0a 2a 2a 20 20 20  deleted on.**   
379c0 20 20 20 20 20 20 20 74 68 65 20 5b 64 61 74 61         the [data
379d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
379e0 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37   D..**.** {H1297
379f0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
37a00 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c  update_hook(D,F,
37a10 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  P)] interface re
37a20 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 0a  turns the value.
37a30 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 50  **          of P
37a40 20 66 6f 72 20 74 68 65 20 70 72 65 76 69 6f 75   for the previou
37a50 73 20 63 61 6c 6c 20 6f 6e 20 74 68 65 20 73 61  s call on the sa
37a60 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
37a70 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20  nection] D,.**  
37a80 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20          or NULL 
37a90 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 63 61  for the first ca
37aa0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37  ll..**.** {H1297
37ab0 35 7d 20 49 66 20 74 68 65 20 75 70 64 61 74 65  5} If the update
37ac0 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 46   hook callback F
37ad0 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 75 70 64   in [sqlite3_upd
37ae0 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  ate_hook(D,F,P)]
37af0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
37b00 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 6e 6f  NULL then the no
37b10 20 75 70 64 61 74 65 20 63 61 6c 6c 62 61 63 6b   update callback
37b20 73 20 61 72 65 20 6d 61 64 65 2e 0a 2a 2a 0a 2a  s are made..**.*
37b30 2a 20 7b 48 31 32 39 37 37 7d 20 45 61 63 68 20  * {H12977} Each 
37b40 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
37b50 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46  _update_hook(D,F
37b60 2c 50 29 5d 20 6f 76 65 72 72 69 64 65 73 20 70  ,P)] overrides p
37b70 72 69 6f 72 20 63 61 6c 6c 73 0a 2a 2a 20 20 20  rior calls.**   
37b80 20 20 20 20 20 20 20 74 6f 20 74 68 65 20 73 61         to the sa
37b90 6d 65 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 20  me interface on 
37ba0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
37bb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
37bc0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37 39 7d  ..**.** {H12979}
37bd0 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
37be0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74   callback is not
37bf0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e   invoked when in
37c00 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 0a 2a 2a  ternal system.**
37c10 20 20 20 20 20 20 20 20 20 20 74 61 62 6c 65 73            tables
37c20 20 73 75 63 68 20 61 73 20 73 71 6c 69 74 65 5f   such as sqlite_
37c30 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74  master and sqlit
37c40 65 5f 73 65 71 75 65 6e 63 65 20 61 72 65 20 6d  e_sequence are m
37c50 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  odified..**.** {
37c60 48 31 32 39 38 31 7d 20 54 68 65 20 73 65 63 6f  H12981} The seco
37c70 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
37c80 74 68 65 20 75 70 64 61 74 65 20 63 61 6c 6c 62  the update callb
37c90 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
37ca0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
37cb0 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49  E_INSERT], [SQLI
37cc0 54 45 5f 44 45 4c 45 54 45 5d 20 6f 72 20 5b 53  TE_DELETE] or [S
37cd0 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 0a 2a  QLITE_UPDATE],.*
37ce0 2a 20 20 20 20 20 20 20 20 20 20 64 65 70 65 6e  *          depen
37cf0 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72  ding on the oper
37d00 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65  ation that cause
37d10 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74  d the callback t
37d20 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
37d30 0a 2a 2a 20 7b 48 31 32 39 38 33 7d 20 54 68 65  .** {H12983} The
37d40 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
37d50 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  h arguments to t
37d60 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  he callback cont
37d70 61 69 6e 20 70 6f 69 6e 74 65 72 73 0a 2a 2a 20  ain pointers.** 
37d80 20 20 20 20 20 20 20 20 20 74 6f 20 7a 65 72 6f           to zero
37d90 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
37da0 38 20 73 74 72 69 6e 67 73 20 77 68 69 63 68 20  8 strings which 
37db0 61 72 65 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  are the names of
37dc0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
37dd0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 61   database and ta
37de0 62 6c 65 20 74 68 61 74 20 69 73 20 62 65 69 6e  ble that is bein
37df0 67 20 75 70 64 61 74 65 64 2e 0a 0a 2a 2a 20 7b  g updated...** {
37e00 48 31 32 39 38 35 7d 20 54 68 65 20 66 69 6e 61  H12985} The fina
37e10 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d  l callback param
37e20 65 74 65 72 20 69 73 20 74 68 65 20 72 6f 77 69  eter is the rowi
37e30 64 20 6f 66 20 74 68 65 20 72 6f 77 20 61 66 74  d of the row aft
37e40 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
37e50 68 65 20 63 68 61 6e 67 65 20 6f 63 63 75 72 73  he change occurs
37e60 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
37e70 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a  e3_update_hook(.
37e80 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
37e90 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e  oid(*)(void *,in
37ea0 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c  t ,char const *,
37eb0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c  char const *,sql
37ec0 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76  ite3_int64),.  v
37ed0 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  oid*.);../*.** C
37ee0 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
37ef0 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65  Or Disable Share
37f00 64 20 50 61 67 65 72 20 43 61 63 68 65 20 7b 48  d Pager Cache {H
37f10 31 30 33 33 30 7d 20 3c 53 33 30 39 30 30 3e 0a  10330} <S30900>.
37f20 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68  ** KEYWORDS: {sh
37f30 61 72 65 64 20 63 61 63 68 65 7d 20 7b 73 68 61  ared cache} {sha
37f40 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 7d 0a  red cache mode}.
37f50 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
37f60 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
37f70 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 69  sables the shari
37f80 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ng of the databa
37f90 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20  se cache.** and 
37fa0 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 75  schema data stru
37fb0 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b  ctures between [
37fc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37fd0 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e  ion | connection
37fe0 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d  s].** to the sam
37ff0 65 20 64 61 74 61 62 61 73 65 2e 20 53 68 61 72  e database. Shar
38000 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ing is enabled i
38010 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
38020 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69  s true.** and di
38030 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  sabled if the ar
38040 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e  gument is false.
38050 0a 2a 2a 0a 2a 2a 20 43 61 63 68 65 20 73 68 61  .**.** Cache sha
38060 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
38070 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72  and disabled for
38080 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65   an entire proce
38090 73 73 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68 69  ss. {END}.** Thi
380a0 73 20 69 73 20 61 20 63 68 61 6e 67 65 20 61 73  s is a change as
380b0 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
380c0 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69  on 3.5.0. In pri
380d0 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  or versions of S
380e0 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e  QLite,.** sharin
380f0 67 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72  g was enabled or
38100 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61   disabled for ea
38110 63 68 20 74 68 72 65 61 64 20 73 65 70 61 72 61  ch thread separa
38120 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tely..**.** The 
38130 63 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  cache sharing mo
38140 64 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69  de set by this i
38150 6e 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73  nterface effects
38160 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a   all subsequent.
38170 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ** calls to [sql
38180 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
38190 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
381a0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
381b0 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78  open16()]..** Ex
381c0 69 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  isting database 
381d0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74  connections cont
381e0 69 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61  inue use the sha
381f0 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61  ring mode.** tha
38200 74 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20  t was in effect 
38210 61 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79  at the time they
38220 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a   were opened..**
38230 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c  .** Virtual tabl
38240 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65  es cannot be use
38250 64 20 77 69 74 68 20 61 20 73 68 61 72 65 64 20  d with a shared 
38260 63 61 63 68 65 2e 20 20 57 68 65 6e 20 73 68 61  cache.  When sha
38270 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
38280 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71  enabled, the [sq
38290 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
382a0 75 6c 65 28 29 5d 20 41 50 49 20 75 73 65 64 20  ule()] API used 
382b0 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76  to register.** v
382c0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69  irtual tables wi
382d0 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
382e0 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a   an error..**.**
382f0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
38300 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
38310 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68  ] if shared cach
38320 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72  e was enabled or
38330 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63   disabled.** suc
38340 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b  cessfully.  An [
38350 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
38360 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73  eturned otherwis
38370 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20  e..**.** Shared 
38380 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65  cache is disable
38390 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75  d by default. Bu
383a0 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 61  t this might cha
383b0 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  nge in.** future
383c0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
383d0 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ite.  Applicatio
383e0 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62 6f  ns that care abo
383f0 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ut shared.** cac
38400 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c  he setting shoul
38410 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 69  d set it explici
38420 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  tly..**.** INVAR
38430 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
38440 30 33 33 31 7d 20 41 20 73 75 63 63 65 73 73 66  0331} A successf
38450 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
38460 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
38470 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 42 29  _shared_cache(B)
38480 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  ].**          wi
38490 6c 6c 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  ll enable or dis
384a0 61 62 6c 65 20 73 68 61 72 65 64 20 63 61 63 68  able shared cach
384b0 65 20 6d 6f 64 65 20 66 6f 72 20 61 6e 79 20 73  e mode for any s
384c0 75 62 73 65 71 75 65 6e 74 6c 79 0a 2a 2a 20 20  ubsequently.**  
384d0 20 20 20 20 20 20 20 20 63 72 65 61 74 65 64 20          created 
384e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
384f0 74 69 6f 6e 5d 20 69 6e 20 74 68 65 20 73 61 6d  tion] in the sam
38500 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  e process..**.**
38510 20 7b 48 31 30 33 33 36 7d 20 57 68 65 6e 20 73   {H10336} When s
38520 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 65  hared cache is e
38530 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c  nabled, the [sql
38540 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
38550 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  le()].**        
38560 20 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c    interface will
38570 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61   always return a
38580 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b  n error..**.** {
38590 48 31 30 33 33 37 7d 20 54 68 65 20 5b 73 71 6c  H10337} The [sql
385a0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
385b0 65 64 5f 63 61 63 68 65 28 42 29 5d 20 69 6e 74  ed_cache(B)] int
385c0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
385d0 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
385e0 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64  TE_OK] if shared
385f0 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c   cache was enabl
38600 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 73  ed or disabled s
38610 75 63 63 65 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a  uccessfully..**.
38620 2a 2a 20 7b 48 31 30 33 33 39 7d 20 53 68 61 72  ** {H10339} Shar
38630 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61  ed cache is disa
38640 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
38650 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
38660 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
38670 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  che(int);../*.**
38680 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d   CAPI3REF: Attem
38690 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20  pt To Free Heap 
386a0 4d 65 6d 6f 72 79 20 7b 48 31 37 33 34 30 7d 20  Memory {H17340} 
386b0 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30220>.**.** T
386c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  he sqlite3_relea
386d0 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65  se_memory() inte
386e0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
386f0 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a  o free N bytes.*
38700 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  * of heap memory
38710 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67   by deallocating
38720 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d   non-essential m
38730 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
38740 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65  s.** held by the
38750 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72   database librar
38760 79 2e 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79  y. {END}  Memory
38770 20 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64   used to cache d
38780 61 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73  atabase.** pages
38790 20 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66   to improve perf
387a0 6f 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78  ormance is an ex
387b0 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73  ample of non-ess
387c0 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a  ential memory..*
387d0 2a 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  * sqlite3_releas
387e0 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72  e_memory() retur
387f0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
38800 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20   bytes actually 
38810 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20  freed,.** which 
38820 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72  might be more or
38830 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61   less than the a
38840 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e  mount requested.
38850 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
38860 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 34 31  S:.**.** {H17341
38870 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
38880 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 4e 29  elease_memory(N)
38890 5d 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ] interface atte
388a0 6d 70 74 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20  mpts to.**      
388b0 20 20 20 20 66 72 65 65 20 4e 20 62 79 74 65 73      free N bytes
388c0 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
388d0 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20  by deallocating 
388e0 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 0a 2a 2a  non-essential.**
388f0 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79