/ Hex Artifact Content
Login

Artifact 30af3a002a0b672aaae8f4a5deb0a2e9a4b699af:


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 34 20 32 30 30 38 2f 30  n,v 1.384 2008/0
05f0: 37 2f 33 31 20 31 37 3a 31 36 3a 30 35 20 64 72  7/31 17:16:05 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 5b 73 71 6c 69 74  **   <li> [sqlit
c4a0: 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20  e3_status()].** 
c4b0: 20 20 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e    </ul>.** </dd>
c4c0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
c4d0: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
c4e0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
c4f0: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
c500: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
c510: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
c520: 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
c530: 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  r.** scratch mem
c540: 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20  ory.  There are 
c550: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
c560: 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74    A pointer to t
c570: 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65 0a 2a  he memory, the.*
c580: 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73  * size of each s
c590: 63 72 61 74 63 68 20 62 75 66 66 65 72 20 28 73  cratch buffer (s
c5a0: 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62  z), and the numb
c5b0: 65 72 20 6f 66 20 62 75 66 66 65 72 73 20 28 4e  er of buffers (N
c5c0: 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72  ).  The sz.** ar
c5d0: 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
c5e0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e   multiple of 16.
c5f0: 20 54 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65   The sz paramete
c600: 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 66 65  r should be a fe
c610: 77 20 62 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65  w bytes.** large
c620: 72 20 74 68 61 6e 20 74 68 65 20 61 63 74 75 61  r than the actua
c630: 6c 20 73 63 72 61 74 63 68 20 73 70 61 63 65 20  l scratch space 
c640: 72 65 71 75 69 72 65 64 20 64 75 65 20 69 6e 74  required due int
c650: 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a  ernal overhead..
c660: 2a 2a 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  ** The first.** 
c670: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
c680: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f  point to an allo
c690: 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61  cation of at lea
c6a0: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
c6b0: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69   memory..** SQLi
c6c0: 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d  te will use no m
c6d0: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72  ore than one scr
c6e0: 61 74 63 68 20 62 75 66 66 65 72 20 61 74 20 6f  atch buffer at o
c6f0: 6e 63 65 20 70 65 72 20 74 68 72 65 61 64 2c 20  nce per thread, 
c700: 73 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62  so.** N should b
c710: 65 20 73 65 74 20 74 6f 20 74 68 65 20 65 78 70  e set to the exp
c720: 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75  ected maximum nu
c730: 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e  mber of threads.
c740: 20 20 54 68 65 20 73 7a 0a 2a 2a 20 70 61 72 61    The sz.** para
c750: 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20  meter should be 
c760: 36 20 74 69 6d 65 73 20 74 68 65 20 73 69 7a 65  6 times the size
c770: 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
c780: 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
c790: 7a 65 2e 0a 2a 2a 20 53 63 72 61 74 63 68 20 62  ze..** Scratch b
c7a0: 75 66 66 65 72 73 20 61 72 65 20 75 73 65 64 20  uffers are used 
c7b0: 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 62  as part of the b
c7c0: 74 72 65 65 20 62 61 6c 61 6e 63 65 20 6f 70 65  tree balance ope
c7d0: 72 61 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54  ration.  If.** T
c7e0: 68 65 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65  he btree balance
c7f0: 72 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e  r needs addition
c800: 61 6c 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64  al memory beyond
c810: 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
c820: 64 20 62 79 0a 2a 2a 20 73 63 72 61 74 63 68 20  d by.** scratch 
c830: 62 75 66 66 65 72 73 20 6f 72 20 69 66 20 6e 6f  buffers or if no
c840: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
c850: 73 70 61 63 65 20 69 73 20 73 70 65 63 69 66 69  space is specifi
c860: 65 64 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a  ed, then SQLite.
c870: 2a 2a 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  ** goes to [sqli
c880: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f  te3_malloc()] to
c890: 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
c8a0: 72 79 20 69 74 20 6e 65 65 64 73 2e 3c 2f 64 64  ry it needs.</dd
c8b0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
c8c0: 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
c8d0: 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
c8e0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
c8f0: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
c900: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
c910: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
c920: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61   for.** the data
c930: 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 2e  base page cache.
c940: 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65    There are thre
c950: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70  e arguments: A p
c960: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
c970: 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
c980: 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
c990: 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
c9a0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
c9b0: 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
c9c0: 73 7a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  sz argument must
c9d0: 20 62 65 20 61 20 70 6f 77 65 72 20 6f 66 20 74   be a power of t
c9e0: 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
c9f0: 6e 64 20 33 32 37 36 38 2e 20 20 54 68 65 20 66  nd 32768.  The f
ca00: 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  irst.** argument
ca10: 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f   should point to
ca20: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f   an allocation o
ca30: 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
ca40: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
ca50: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
ca60: 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
ca70: 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66  rovided by the f
ca80: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
ca90: 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20   satisfy its.** 
caa0: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72  memory needs for
cab0: 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67   the first N pag
cac0: 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20  es that it adds 
cad0: 74 6f 20 63 61 63 68 65 2e 20 20 49 66 20 61 64  to cache.  If ad
cae0: 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
caf0: 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
cb00: 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
cb10: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
cb20: 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
cb30: 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
cb40: 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
cb50: 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
cb60: 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
cb70: 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54  rage space..** T
cb80: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
cb90: 6e 20 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 20  n might use one 
cba0: 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e  or more of the N
cbb0: 20 62 75 66 66 65 72 73 20 74 6f 20 68 6f 6c 64   buffers to hold
cbc0: 20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f   .** memory acco
cbd0: 75 6e 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69  unting informati
cbe0: 6f 6e 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  on. </dd>.**.** 
cbf0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
cc00: 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
cc10: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  dd>This option s
cc20: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
cc30: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
cc40: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
cc50: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20   use.** for all 
cc60: 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
cc70: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
cc80: 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68   needs beyond th
cc90: 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ose provided.** 
cca0: 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
ccb0: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
ccc0: 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  nd [SQLITE_CONFI
ccd0: 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
cce0: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
ccf0: 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f   arguments: A po
cd00: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
cd10: 6f 72 79 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ory, the number 
cd20: 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
cd30: 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
cd40: 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
cd50: 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
cd60: 65 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 66 69  e.  If.** the fi
cd70: 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
cd80: 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
cd90: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
cda0: 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
cdb0: 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
cdc0: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
cdd0: 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
cde0: 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
cdf0: 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
ce00: 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
ce10: 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
ce20: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
ce30: 41 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65 0a  ALLOC].  If the.
ce40: 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
ce50: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  r is not NULL an
ce60: 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  d either [SQLITE
ce70: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
ce80: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45   or.** [SQLITE_E
ce90: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
cea0: 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e  re defined, then
ceb0: 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
cec0: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
ced0: 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
cee0: 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
cef0: 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
cf00: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
cf10: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
cf20: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
cf30: 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
cf40: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  >This option tak
cf50: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
cf60: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
cf70: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
cf80: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
cf90: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
cfa0: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
cfb0: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
cfc0: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
cfd0: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
cfe0: 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
cff0: 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
d000: 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d  n place.** the m
d010: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
d020: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
d030: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
d040: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
d050: 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  TMUTEX</dt>.** <
d060: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
d070: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
d080: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
d090: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
d0a0: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
d0b0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
d0c0: 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
d0d0: 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
d0e0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
d0f0: 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
d100: 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
d110: 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
d120: 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
d130: 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20  utines..** This 
d140: 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
d150: 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
d160: 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
d170: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
d180: 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
d190: 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
d1a0: 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
d1b0: 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
d1c0: 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
d1d0: 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
d1e0: 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ample.</dd>.**.*
d1f0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d200: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
d210: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
d220: 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
d230: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
d240: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66  etermine the def
d250: 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  ault.** memory a
d260: 6c 6c 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69  llcation lookasi
d270: 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e  de optimization.
d280: 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
d290: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
d2a0: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
d2b0: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
d2c0: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
d2d0: 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
d2e0: 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
d2f0: 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
d300: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d310: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64  .</dd>.**.** </d
d320: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
d330: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
d340: 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
d350: 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
d360: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
d370: 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
d380: 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
d390: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
d3a0: 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
d3b0: 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
d3c0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
d3d0: 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
d3e0: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
d3f0: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
d400: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
d410: 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
d420: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
d430: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
d440: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
d450: 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
d460: 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   6  /* void*, in
d470: 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
d480: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
d490: 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20  NFIG_PAGECACHE  
d4a0: 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     7  /* void*, 
d4b0: 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
d4c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d4d0: 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20  CONFIG_HEAP     
d4e0: 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a       8  /* void*
d4f0: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74  , int nByte, int
d500: 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20   min */.#define 
d510: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
d520: 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f  MSTATUS     9  /
d530: 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65  * boolean */.#de
d540: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
d550: 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20  IG_MUTEX        
d560: 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  10  /* sqlite3_m
d570: 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
d580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d590: 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
d5a0: 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74      11  /* sqlit
d5b0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
d5c0: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
d5d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
d5e0: 41 4c 4c 4f 43 20 20 20 31 32 20 20 2f 2a 20 69  ALLOC   12  /* i
d5f0: 6e 74 20 74 68 72 65 73 68 6f 6c 64 20 2a 2f 0a  nt threshold */.
d600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
d610: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
d620: 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e     13  /* int in
d630: 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t */.../*.** CAP
d640: 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
d650: 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65   Disable Extende
d660: 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20 7b  d Result Codes {
d670: 48 31 32 32 30 30 7d 20 3c 53 31 30 37 30 30 3e  H12200} <S10700>
d680: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
d690: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
d6a0: 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
d6b0: 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
d6c0: 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
d6d0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
d6e0: 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
d6f0: 20 53 51 4c 69 74 65 2e 20 54 68 65 20 65 78 74   SQLite. The ext
d700: 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20  ended result.** 
d710: 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
d720: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
d730: 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d  r historical com
d740: 70 61 74 69 62 69 6c 69 74 79 20 63 6f 6e 73 69  patibility consi
d750: 64 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  derations..**.**
d760: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
d770: 2a 2a 20 7b 48 31 32 32 30 31 7d 20 45 61 63 68  ** {H12201} Each
d780: 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63   new [database c
d790: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 68 61 6c 6c  onnection] shall
d7a0: 20 68 61 76 65 20 74 68 65 0a 2a 2a 20 20 20 20   have the.**    
d7b0: 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20        [extended 
d7c0: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
d7d0: 61 74 75 72 65 20 64 69 73 61 62 6c 65 64 20 62  ature disabled b
d7e0: 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
d7f0: 20 7b 48 31 32 32 30 32 7d 20 54 68 65 20 5b 73   {H12202} The [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 44 2c 46  result_codes(D,F
d820: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  )] interface sha
d830: 6c 6c 20 65 6e 61 62 6c 65 0a 2a 2a 20 20 20 20  ll enable.**    
d840: 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65 64 20        [extended 
d850: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 6f  result codes] fo
d860: 72 20 74 68 65 20 20 5b 64 61 74 61 62 61 73 65  r the  [database
d870: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
d880: 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74 68  *          if th
d890: 65 20 46 20 70 61 72 61 6d 65 74 65 72 20 69 73  e F parameter is
d8a0: 20 74 72 75 65 2c 20 6f 72 20 64 69 73 61 62 6c   true, or disabl
d8b0: 65 20 74 68 65 6d 20 69 66 20 46 20 69 73 20 66  e them if F is f
d8c0: 61 6c 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  alse..*/.int sql
d8d0: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
d8e0: 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
d8f0: 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
d900: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
d910: 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
d920: 77 69 64 20 7b 48 31 32 32 32 30 7d 20 3c 53 31  wid {H12220} <S1
d930: 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 61 63 68  0700>.**.** Each
d940: 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c   entry in an SQL
d950: 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  ite table has a 
d960: 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
d970: 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
d980: 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 22  key called the "
d990: 72 6f 77 69 64 22 2e 20 54 68 65 20 72 6f 77 69  rowid". The rowi
d9a0: 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
d9b0: 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
d9c0: 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
d9d0: 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
d9e0: 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
d9f0: 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
da00: 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
da10: 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
da20: 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
da30: 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20   columns. If.** 
da40: 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
da50: 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 49  column of type I
da60: 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
da70: 45 59 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  EY then that col
da80: 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
da90: 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
daa0: 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rowid..**.** Thi
dab0: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
dac0: 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20 74  s the rowid of t
dad0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
dae0: 2a 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53  * successful INS
daf0: 45 52 54 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ERT into the dat
db00: 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b  abase from the [
db10: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
db20: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
db30: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20  irst argument.  
db40: 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
db50: 20 49 4e 53 45 52 54 73 0a 2a 2a 20 68 61 76 65   INSERTs.** have
db60: 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f   ever occurred o
db70: 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20  n that database 
db80: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f  connection, zero
db90: 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
dba0: 0a 2a 2a 20 49 66 20 61 6e 20 49 4e 53 45 52 54  .** If an INSERT
dbb0: 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
dbc0: 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74   trigger, then t
dbd0: 68 65 20 72 6f 77 69 64 20 6f 66 20 74 68 65 20  he rowid of the 
dbe0: 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20  inserted.** row 
dbf0: 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  is returned by t
dc00: 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c  his routine as l
dc10: 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
dc20: 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  er is running..*
dc30: 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74  * But once the t
dc40: 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65  rigger terminate
dc50: 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
dc60: 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f  urned by this ro
dc70: 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73  utine.** reverts
dc80: 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c   to the last val
dc90: 75 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f  ue inserted befo
dca0: 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 66  re the trigger f
dcb0: 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 49  ired..**.** An I
dcc0: 4e 53 45 52 54 20 74 68 61 74 20 66 61 69 6c 73  NSERT that fails
dcd0: 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
dce0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
dcf0: 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
dd00: 73 73 66 75 6c 20 49 4e 53 45 52 54 20 61 6e 64  ssful INSERT and
dd10: 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
dd20: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
dd30: 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
dd40: 6f 75 74 69 6e 65 2e 20 20 54 68 75 73 20 49 4e  outine.  Thus IN
dd50: 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
dd60: 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
dd70: 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
dd80: 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
dd90: 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
dda0: 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
ddb0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
ddc0: 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
ddd0: 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
dde0: 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57  ertion fails.  W
ddf0: 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
de00: 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
de10: 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
de20: 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
de30: 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
de40: 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
de50: 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
de60: 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
de70: 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
de80: 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
de90: 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
dea0: 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
deb0: 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
dec0: 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
ded0: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
dee0: 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
def0: 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70  .** For the purp
df00: 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
df10: 74 69 6e 65 2c 20 61 6e 20 49 4e 53 45 52 54 20  tine, an INSERT 
df20: 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
df30: 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
df40: 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
df50: 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
df60: 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
df70: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
df80: 2a 20 7b 48 31 32 32 32 31 7d 20 54 68 65 20 5b  * {H12221} The [
df90: 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
dfa0: 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e  ert_rowid()] fun
dfb0: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
dfc0: 65 20 72 6f 77 69 64 0a 2a 2a 20 20 20 20 20 20  e rowid.**      
dfd0: 20 20 20 20 6f 66 20 74 68 65 20 6d 6f 73 74 20      of the most 
dfe0: 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75  recent successfu
dff0: 6c 20 49 4e 53 45 52 54 20 70 65 72 66 6f 72 6d  l INSERT perform
e000: 65 64 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  ed on the same.*
e010: 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61  *          [data
e020: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
e030: 20 61 6e 64 20 77 69 74 68 69 6e 20 74 68 65 20   and within the 
e040: 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72 20 6c  same or higher l
e050: 65 76 65 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  evel.**         
e060: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
e070: 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65  , or zero if the
e080: 72 65 20 68 61 76 65 20 62 65 65 6e 20 6e 6f 20  re have been no 
e090: 71 75 61 6c 69 66 79 69 6e 67 20 69 6e 73 65 72  qualifying inser
e0a0: 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32  ts..**.** {H1222
e0b0: 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
e0c0: 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
e0d0: 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65  d()] function re
e0e0: 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20  turns the.**    
e0f0: 20 20 20 20 20 20 73 61 6d 65 20 76 61 6c 75 65        same value
e100: 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
e110: 6d 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  m the same trigg
e120: 65 72 20 63 6f 6e 74 65 78 74 0a 2a 2a 20 20 20  er context.**   
e130: 20 20 20 20 20 20 20 69 6d 6d 65 64 69 61 74 65         immediate
e140: 6c 79 20 62 65 66 6f 72 65 20 61 6e 64 20 61 66  ly before and af
e150: 74 65 72 20 61 20 52 4f 4c 4c 42 41 43 4b 2e 0a  ter a ROLLBACK..
e160: 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e  **.** ASSUMPTION
e170: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 33 32  S:.**.** {A12232
e180: 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  } If a separate 
e190: 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20  thread performs 
e1a0: 61 20 6e 65 77 20 49 4e 53 45 52 54 20 6f 6e 20  a new INSERT on 
e1b0: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20  the same.**     
e1c0: 20 20 20 20 20 64 61 74 61 62 61 73 65 20 63 6f       database co
e1d0: 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
e1e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
e1f0: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
e200: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75 6e  .**          fun
e210: 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
e220: 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
e230: 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
e240: 74 20 72 6f 77 69 64 2c 0a 2a 2a 20 20 20 20 20  t rowid,.**     
e250: 20 20 20 20 20 74 68 65 6e 20 74 68 65 20 76 61       then the va
e260: 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
e270: 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
e280: 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
e290: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e 70  .**          unp
e2a0: 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d  redictable and m
e2b0: 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65  ight not equal e
e2c0: 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72  ither the old or
e2d0: 20 74 68 65 20 6e 65 77 0a 2a 2a 20 20 20 20 20   the new.**     
e2e0: 20 20 20 20 20 6c 61 73 74 20 69 6e 73 65 72 74       last insert
e2f0: 20 72 6f 77 69 64 2e 0a 2a 2f 0a 73 71 6c 69 74   rowid..*/.sqlit
e300: 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
e310: 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
e320: 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
e330: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
e340: 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
e350: 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
e360: 20 7b 48 31 32 32 34 30 7d 20 3c 53 31 30 36 30   {H12240} <S1060
e370: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0>.**.** This fu
e380: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
e390: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
e3a0: 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
e3b0: 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
e3c0: 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
e3d0: 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
e3e0: 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
e3f0: 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  leted SQL statem
e400: 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64  ent.** on the [d
e410: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
e420: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
e430: 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
e440: 65 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68  eter..** Only ch
e450: 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
e460: 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
e470: 64 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c  d by the INSERT,
e480: 20 55 50 44 41 54 45 2c 0a 2a 2a 20 6f 72 20 44   UPDATE,.** or D
e490: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
e4a0: 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75  are counted.  Au
e4b0: 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
e4c0: 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69  caused by.** tri
e4d0: 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f  ggers are not co
e4e0: 75 6e 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b  unted. Use the [
e4f0: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
e500: 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
e510: 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65  n.** to find the
e520: 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
e530: 20 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69   changes includi
e540: 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ng changes cause
e550: 64 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a  d by triggers..*
e560: 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e  *.** A "row chan
e570: 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20  ge" is a change 
e580: 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  to a single row 
e590: 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c  of a single tabl
e5a0: 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61  e.** caused by a
e5b0: 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45  n INSERT, DELETE
e5c0: 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74  , or UPDATE stat
e5d0: 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61  ement.  Rows tha
e5e0: 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64  t.** are changed
e5f0: 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73   as side effects
e600: 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73   of REPLACE cons
e610: 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
e620: 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
e630: 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
e640: 2c 20 44 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72  , DROP TABLE, or
e650: 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
e660: 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
e670: 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
e680: 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a  ct row changes..
e690: 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72  **.** A "trigger
e6a0: 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73   context" is a s
e6b0: 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f  cope of executio
e6c0: 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e  n that begins an
e6d0: 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74  d.** ends with t
e6e0: 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 74  he script of a t
e6f0: 72 69 67 67 65 72 2e 20 20 4d 6f 73 74 20 53 51  rigger.  Most SQ
e700: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
e710: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75  .** evaluated ou
e720: 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69  tside of any tri
e730: 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74  gger.  This is t
e740: 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a  he "top level".*
e750: 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
e760: 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72  t.  If a trigger
e770: 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20   fires from the 
e780: 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20  top level, a.** 
e790: 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
e7a0: 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66  ext is entered f
e7b0: 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20  or the duration 
e7c0: 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74  of that one.** t
e7d0: 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67  rigger.  Subtrig
e7e0: 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63  gers create subc
e7f0: 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69  ontexts for thei
e800: 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  r duration..**.*
e810: 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * Calling [sqlit
e820: 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
e830: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
e840: 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
e850: 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
e860: 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
e870: 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ext..**.** This 
e880: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
e890: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
e8a0: 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
e8b0: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74  s in the.** most
e8c0: 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
e8d0: 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
e8e0: 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
e8f0: 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74  in the same.** t
e900: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
e910: 2a 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e  **.** Thus, when
e920: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
e930: 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73   top level, this
e940: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
e950: 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
e960: 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  of changes in th
e970: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
e980: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
e990: 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
e9a0: 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74  also occurred at
e9b0: 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20   the top level. 
e9c0: 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   Within the body
e9d0: 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a   of a trigger,.*
e9e0: 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  * the sqlite3_ch
e9f0: 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63  anges() interfac
ea00: 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
ea10: 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
ea20: 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73  er of.** changes
ea30: 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
ea40: 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
ea50: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
ea60: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
ea70: 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
ea80: 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61  e body of the sa
ea90: 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48  me trigger..** H
eaa0: 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62  owever, the numb
eab0: 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  er returned does
eac0: 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
ead0: 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62  nges.** caused b
eae0: 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69  y subtriggers si
eaf0: 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74  nce those have t
eb00: 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74  heir own context
eb10: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
eb20: 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f  mplements the co
eb30: 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52  mmand "DELETE FR
eb40: 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75  OM table" withou
eb50: 74 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65  t a WHERE clause
eb60: 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20  .** by dropping 
eb70: 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74  and recreating t
eb80: 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73  he table.  (This
eb90: 20 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20   is much faster 
eba0: 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68  than going.** th
ebb0: 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69  rough and deleti
ebc0: 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c  ng individual el
ebd0: 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20  ements from the 
ebe0: 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65  table.)  Because
ebf0: 20 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69   of this.** opti
ec00: 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65  mization, the de
ec10: 6c 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45  letions in "DELE
ec20: 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61  TE FROM table" a
ec30: 72 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67  re not row chang
ec40: 65 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e  es and.** will n
ec50: 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79  ot be counted by
ec60: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
ec70: 6e 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74  nges() or [sqlit
ec80: 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
ec90: 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ()].** functions
eca0: 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
ecb0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c  the number of el
ecc0: 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65  ements that were
ecd0: 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69   originally.** i
ece0: 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f  n the table.  To
ecf0: 20 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65   get an accurate
ed00: 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75   count of the nu
ed10: 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c  mber of rows del
ed20: 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45  eted, use.** "DE
ed30: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20  LETE FROM table 
ed40: 57 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64  WHERE 1" instead
ed50: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
ed60: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34  TS:.**.** {H1224
ed70: 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
ed80: 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74  changes()] funct
ed90: 69 6f 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  ion shall return
eda0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
edb0: 2a 20 20 20 20 20 20 20 20 20 20 72 6f 77 20 63  *          row c
edc0: 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
edd0: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
ede0: 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
edf0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
ee00: 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
ee10: 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
ee20: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ee30: 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
ee40: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
ee50: 20 6f 72 20 68 69 67 68 65 72 20 74 72 69 67 67   or higher trigg
ee60: 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a  er context, or z
ee70: 65 72 6f 20 69 66 20 74 68 65 72 65 20 68 61 76  ero if there hav
ee80: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f  e.**          no
ee90: 74 20 62 65 65 6e 20 61 6e 79 20 71 75 61 6c 69  t been any quali
eea0: 66 79 69 6e 67 20 72 6f 77 20 63 68 61 6e 67 65  fying row change
eeb0: 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 34 33  s..**.** {H12243
eec0: 7d 20 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  } Statements of 
eed0: 74 68 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45  the form "DELETE
eee0: 20 46 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22   FROM tablename"
eef0: 20 77 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20   with no.**     
ef00: 20 20 20 20 20 57 48 45 52 45 20 63 6c 61 75 73       WHERE claus
ef10: 65 20 73 68 61 6c 6c 20 63 61 75 73 65 20 73 75  e shall cause su
ef20: 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
ef30: 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
ef40: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
ef50: 5d 20 74 6f 20 72 65 74 75 72 6e 20 7a 65 72 6f  ] to return zero
ef60: 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
ef70: 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
ef80: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6f  number of rows o
ef90: 72 69 67 69 6e 61 6c 6c 79 20 69 6e 20 74 68 65  riginally in the
efa0: 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 53   table..**.** AS
efb0: 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
efc0: 20 7b 41 31 32 32 35 32 7d 20 49 66 20 61 20 73   {A12252} If a s
efd0: 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
efe0: 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
eff0: 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
f000: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
f010: 20 20 20 20 20 20 20 20 20 77 68 69 6c 65 20 5b           while [
f020: 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
f030: 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
f040: 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
f050: 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  urned.**        
f060: 20 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62    is unpredictab
f070: 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
f080: 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
f090: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71  lite3_changes(sq
f0a0: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
f0b0: 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20  CAPI3REF: Total 
f0c0: 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
f0d0: 6f 64 69 66 69 65 64 20 7b 48 31 32 32 36 30 7d  odified {H12260}
f0e0: 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10600>.**.** 
f0f0: 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
f100: 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
f110: 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20   of row changes 
f120: 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52 54  caused by INSERT
f130: 2c 0a 2a 2a 20 55 50 44 41 54 45 20 6f 72 20 44  ,.** UPDATE or D
f140: 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 73  ELETE statements
f150: 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61   since the [data
f160: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
f170: 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20   was opened..** 
f180: 54 68 65 20 63 6f 75 6e 74 20 69 6e 63 6c 75 64  The count includ
f190: 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 20 66  es all changes f
f1a0: 72 6f 6d 20 61 6c 6c 20 74 72 69 67 67 65 72 20  rom all trigger 
f1b0: 63 6f 6e 74 65 78 74 73 2e 20 20 48 6f 77 65 76  contexts.  Howev
f1c0: 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74  er,.** the count
f1d0: 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
f1e0: 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74  e changes used t
f1f0: 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 52 45 50 4c  o implement REPL
f200: 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c  ACE constraints,
f210: 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73  .** do rollbacks
f220: 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73   or ABORT proces
f230: 73 69 6e 67 2c 20 6f 72 20 44 52 4f 50 20 74 61  sing, or DROP ta
f240: 62 6c 65 20 70 72 6f 63 65 73 73 69 6e 67 2e 0a  ble processing..
f250: 2a 2a 20 54 68 65 20 63 68 61 6e 67 65 73 20 61  ** The changes a
f260: 72 65 20 63 6f 75 6e 74 65 64 20 61 73 20 73 6f  re counted as so
f270: 6f 6e 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  on as the statem
f280: 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74  ent that makes t
f290: 68 65 6d 20 69 73 0a 2a 2a 20 63 6f 6d 70 6c 65  hem is.** comple
f2a0: 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74  ted (when the st
f2b0: 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 69  atement handle i
f2c0: 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
f2d0: 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
f2e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
f2f0: 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a  alize()])..**.**
f300: 20 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e   SQLite implemen
f310: 74 73 20 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22  ts the command "
f320: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
f330: 65 22 20 77 69 74 68 6f 75 74 20 61 20 57 48 45  e" without a WHE
f340: 52 45 20 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20  RE clause.** by 
f350: 64 72 6f 70 70 69 6e 67 20 61 6e 64 20 72 65 63  dropping and rec
f360: 72 65 61 74 69 6e 67 20 74 68 65 20 74 61 62 6c  reating the tabl
f370: 65 2e 20 20 28 54 68 69 73 20 69 73 20 6d 75 63  e.  (This is muc
f380: 68 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f  h faster than go
f390: 69 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  ing.** through a
f3a0: 6e 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69  nd deleting indi
f3b0: 76 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20  vidual elements 
f3c0: 66 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 29  from the table.)
f3d0: 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 69    Because of thi
f3e0: 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f  s.** optimizatio
f3f0: 6e 2c 20 74 68 65 20 64 65 6c 65 74 69 6f 6e 73  n, the deletions
f400: 20 69 6e 20 22 44 45 4c 45 54 45 20 46 52 4f 4d   in "DELETE FROM
f410: 20 74 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 20   table" are not 
f420: 72 6f 77 20 63 68 61 6e 67 65 73 20 61 6e 64 0a  row changes and.
f430: 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63  ** will not be c
f440: 6f 75 6e 74 65 64 20 62 79 20 74 68 65 20 73 71  ounted by the sq
f450: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
f460: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  or [sqlite3_tota
f470: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20  l_changes()].** 
f480: 66 75 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61 72  functions, regar
f490: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d  dless of the num
f4a0: 62 65 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20  ber of elements 
f4b0: 74 68 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e  that were origin
f4c0: 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74  ally.** in the t
f4d0: 61 62 6c 65 2e 20 20 54 6f 20 67 65 74 20 61 6e  able.  To get an
f4e0: 20 61 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20   accurate count 
f4f0: 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
f500: 20 72 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75   rows deleted, u
f510: 73 65 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52  se.** "DELETE FR
f520: 4f 4d 20 74 61 62 6c 65 20 57 48 45 52 45 20 31  OM table WHERE 1
f530: 22 20 69 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a  " instead..**.**
f540: 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
f550: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
f560: 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
f570: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
f580: 2a 0a 2a 2a 20 7b 48 31 32 32 36 31 7d 20 54 68  *.** {H12261} Th
f590: 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
f5a0: 5f 63 68 61 6e 67 65 73 28 29 5d 20 72 65 74 75  _changes()] retu
f5b0: 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  rns the total nu
f5c0: 6d 62 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  mber.**         
f5d0: 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20   of row changes 
f5e0: 63 61 75 73 65 64 20 62 79 20 49 4e 53 45 52 54  caused by INSERT
f5f0: 2c 20 55 50 44 41 54 45 2c 20 61 6e 64 2f 6f 72  , UPDATE, and/or
f600: 20 44 45 4c 45 54 45 0a 2a 2a 20 20 20 20 20 20   DELETE.**      
f610: 20 20 20 20 73 74 61 74 65 6d 65 6e 74 73 20 6f      statements o
f620: 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
f630: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
f640: 2c 20 69 6e 20 61 6e 79 0a 2a 2a 20 20 20 20 20  , in any.**     
f650: 20 20 20 20 20 74 72 69 67 67 65 72 20 63 6f 6e       trigger con
f660: 74 65 78 74 2c 20 73 69 6e 63 65 20 74 68 65 20  text, since the 
f670: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f680: 69 6f 6e 20 77 61 73 20 63 72 65 61 74 65 64 2e  ion was created.
f690: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 36 33 7d 20  .**.** {H12263} 
f6a0: 53 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 74 68  Statements of th
f6b0: 65 20 66 6f 72 6d 20 22 44 45 4c 45 54 45 20 46  e form "DELETE F
f6c0: 52 4f 4d 20 74 61 62 6c 65 6e 61 6d 65 22 20 77  ROM tablename" w
f6d0: 69 74 68 20 6e 6f 0a 2a 2a 20 20 20 20 20 20 20  ith no.**       
f6e0: 20 20 20 57 48 45 52 45 20 63 6c 61 75 73 65 20     WHERE clause 
f6f0: 73 68 61 6c 6c 20 6e 6f 74 20 63 68 61 6e 67 65  shall not change
f700: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
f710: 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ned.**          
f720: 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  by [sqlite3_tota
f730: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 2e 0a 2a 2a  l_changes()]..**
f740: 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
f750: 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 36 34 7d 20  .**.** {A12264} 
f760: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
f770: 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
f780: 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
f790: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f7a0: 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  on.**          w
f7b0: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
f7c0: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
f7d0: 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
f7e0: 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20 20  he value.**     
f7f0: 20 20 20 20 20 72 65 74 75 72 6e 65 64 20 69 73       returned is
f800: 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
f810: 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
f820: 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
f830: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
f840: 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
f850: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
f860: 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
f870: 6e 69 6e 67 20 51 75 65 72 79 20 7b 48 31 32 32  ning Query {H122
f880: 37 30 7d 20 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a  70} <S30500>.**.
f890: 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
f8a0: 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
f8b0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
f8c0: 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
f8d0: 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
f8e0: 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
f8f0: 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
f900: 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
f910: 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
f920: 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
f930: 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
f940: 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
f950: 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
f960: 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
f970: 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
f980: 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
f990: 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
f9a0: 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ately..**.** It 
f9b0: 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
f9c0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
f9d0: 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
f9e0: 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
f9f0: 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
fa00: 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
fa10: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
fa20: 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
fa30: 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
fa40: 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
fa50: 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
fa60: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
fa70: 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
fa80: 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
fa90: 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
faa0: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
fab0: 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
fac0: 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
fad0: 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
fae0: 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
faf0: 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
fb00: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
fb10: 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
fb20: 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
fb30: 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
fb40: 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
fb50: 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
fb60: 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
fb70: 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
fb80: 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
fb90: 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
fba0: 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
fbb0: 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
fbc0: 50 54 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 69  PT]..** If the i
fbd0: 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
fbe0: 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
fbf0: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
fc00: 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
fc10: 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
fc20: 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
fc30: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
fc40: 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
fc50: 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
fc60: 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
fc70: 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ally..**.** A ca
fc80: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
fc90: 74 65 72 72 75 70 74 28 29 20 68 61 73 20 6e 6f  terrupt() has no
fca0: 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
fcb0: 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
fcc0: 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
fcd0: 74 65 72 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ter sqlite3_inte
fce0: 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
fcf0: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
fd00: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37 31  S:.**.** {H12271
fd10: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  } The [sqlite3_i
fd20: 6e 74 65 72 72 75 70 74 28 29 5d 20 69 6e 74 65  nterrupt()] inte
fd30: 72 66 61 63 65 20 77 69 6c 6c 20 66 6f 72 63 65  rface will force
fd40: 20 61 6c 6c 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20   all running.** 
fd50: 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61           SQL sta
fd60: 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
fd70: 65 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ed with the same
fd80: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
fd90: 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
fda0: 20 74 6f 20 68 61 6c 74 20 61 66 74 65 72 20 70   to halt after p
fdb0: 72 6f 63 65 73 73 69 6e 67 20 61 74 20 6d 6f 73  rocessing at mos
fdc0: 74 20 6f 6e 65 20 61 64 64 69 74 69 6f 6e 61 6c  t one additional
fdd0: 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
fde0: 0a 2a 2a 20 7b 48 31 32 32 37 32 7d 20 41 6e 79  .** {H12272} Any
fdf0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
fe00: 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
fe10: 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 69  ed by [sqlite3_i
fe20: 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 20  nterrupt()].**  
fe30: 20 20 20 20 20 20 20 20 77 69 6c 6c 20 72 65 74          will ret
fe40: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
fe50: 52 52 55 50 54 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53  RRUPT]..**.** AS
fe60: 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
fe70: 20 7b 41 31 32 32 37 39 7d 20 49 66 20 74 68 65   {A12279} If the
fe80: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
fe90: 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c  tion closes whil
fea0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
feb0: 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20  rupt()].**      
fec0: 20 20 20 20 69 73 20 72 75 6e 6e 69 6e 67 20 74      is running t
fed0: 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77  hen bad things w
fee0: 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65  ill likely happe
fef0: 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  n..*/.void sqlit
ff00: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
ff10: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
ff20: 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
ff30: 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
ff40: 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
ff50: 74 65 20 7b 48 31 30 35 31 30 7d 20 3c 53 37 30  te {H10510} <S70
ff60: 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  200>.**.** These
ff70: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
ff80: 65 66 75 6c 20 66 6f 72 20 63 6f 6d 6d 61 6e 64  eful for command
ff90: 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
ffa0: 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
ffb0: 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
ffc0: 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
ffd0: 74 6f 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 74 65  to form complete
ffe0: 20 61 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74   a SQL statement
fff0: 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
10000 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
10010 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
10020 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
10030 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
10040 70 61 72 73 69 6e 67 2e 20 20 54 68 65 73 65 20  parsing.  These 
10050 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
10060 74 72 75 65 20 69 66 20 74 68 65 20 69 6e 70 75  true if the inpu
10070 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
10080 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
10090 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
100a0 6e 74 2e 20 20 41 20 73 74 61 74 65 6d 65 6e 74  nt.  A statement
100b0 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
100c0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
100d0 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
100e0 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
100f0 6e 64 20 69 73 20 6e 6f 74 20 61 20 66 72 61 67  nd is not a frag
10100 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 43 52 45  ment of a.** CRE
10110 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
10120 65 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f  ement.  Semicolo
10130 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
10140 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
10150 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
10160 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
10170 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
10180 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
10190 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
101a0 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
101b0 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
101c0 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
101d0 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
101e0 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
101f0 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
10200 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ent terminator..
10210 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
10220 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
10230 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
10240 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
10250 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
10260 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
10270 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
10280 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
10290 2a 20 7b 48 31 30 35 31 31 7d 20 41 20 73 75 63  * {H10511} A suc
102a0 63 65 73 73 66 75 6c 20 65 76 61 6c 75 61 74 69  cessful evaluati
102b0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 63  on of [sqlite3_c
102c0 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 0a 2a 2a  omplete()] or.**
102d0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
102e0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
102f0 20 66 75 6e 63 74 69 6f 6e 73 20 73 68 61 6c 6c   functions shall
10300 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
10310 75 72 6e 20 61 20 6e 75 6d 65 72 69 63 20 31 20  urn a numeric 1 
10320 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
10330 68 65 20 6c 61 73 74 20 6e 6f 6e 2d 77 68 69 74  he last non-whit
10340 65 73 70 61 63 65 0a 2a 2a 20 20 20 20 20 20 20  espace.**       
10350 20 20 20 74 6f 6b 65 6e 20 69 6e 20 74 68 65 69     token in thei
10360 72 20 69 6e 70 75 74 20 69 73 20 61 20 73 65 6d  r input is a sem
10370 69 63 6f 6c 6f 6e 20 74 68 61 74 20 69 73 20 6e  icolon that is n
10380 6f 74 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ot in between.**
10390 20 20 20 20 20 20 20 20 20 20 74 68 65 20 42 45            the BE
103a0 47 49 4e 20 61 6e 64 20 45 4e 44 20 6f 66 20 61  GIN and END of a
103b0 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
103c0 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
103d0 20 7b 48 31 30 35 31 32 7d 20 49 66 20 61 20 6d   {H10512} If a m
103e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
103f0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
10400 72 69 6e 67 20 61 6e 20 69 6e 76 6f 63 61 74 69  ring an invocati
10410 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  on.**          o
10420 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  f [sqlite3_compl
10430 65 74 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ete()] or [sqlit
10440 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
10450 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20   then the.**    
10460 20 20 20 20 20 20 72 6f 75 74 69 6e 65 20 73 68        routine sh
10470 61 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  all return [SQLI
10480 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
10490 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a   ASSUMPTIONS:.**
104a0 0a 2a 2a 20 7b 41 31 30 35 31 32 7d 20 54 68 65  .** {A10512} The
104b0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
104c0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
104d0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
104e0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20  rminated.**     
104f0 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e       UTF-8 strin
10500 67 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31 33  g..**.** {A10513
10510 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  } The input to [
10520 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
10530 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  16()] must be a 
10540 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
10550 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d  **          UTF-
10560 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
10570 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
10580 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
10590 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
105a0 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71  ar *sql);.int sq
105b0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
105c0 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
105d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
105e0 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
105f0 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
10600 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
10610 72 6f 72 73 20 7b 48 31 32 33 31 30 7d 20 3c 53  rors {H12310} <S
10620 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  40400>.**.** Thi
10630 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
10640 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
10650 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  on that might be
10660 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
10670 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
10680 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
10690 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
106a0 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
106b0 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
106c0 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a  ss has locked..*
106d0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79  *.** If the busy
106e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
106f0 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
10700 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
10710 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
10720 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
10730 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
10740 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
10750 20 6c 6f 63 6b 2e 20 49 66 20 74 68 65 20 62 75   lock. If the bu
10760 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
10770 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
10780 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69   the callback wi
10790 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ll be invoked wi
107a0 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
107b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
107c0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
107d0 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  e handler is a c
107e0 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
107f0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
10800 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
10810 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
10820 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
10830 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
10840 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
10850 65 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  e handler callba
10860 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
10870 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
10880 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
10890 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
108a0 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
108b0 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 49 66 20  king event.  If 
108c0 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
108d0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
108e0 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
108f0 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
10900 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
10910 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
10920 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
10930 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
10940 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65  R_BLOCKED] is re
10950 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68  turned..** If th
10960 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
10970 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
10980 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
10990 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
109a0 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
109b0 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
109c0 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
109d0 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
109e0 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
109f0 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
10a00 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
10a10 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
10a20 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
10a30 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
10a40 6e 74 69 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65  ntion. If SQLite
10a50 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
10a60 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
10a70 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
10a80 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
10a90 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
10aa0 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
10ab0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
10ac0 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  SY].** or [SQLIT
10ad0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
10ae0 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f   instead of invo
10af0 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61  king the busy ha
10b00 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
10b10 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
10b20 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
10b30 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
10b40 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
10b50 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
10b60 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
10b70 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
10b80 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
10b90 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
10ba0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
10bb0 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
10bc0 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
10bd0 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
10be0 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
10bf0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
10c00 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
10c10 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
10c20 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
10c30 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
10c40 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
10c50 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
10c60 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
10c70 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
10c80 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
10c90 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
10ca0 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
10cb0 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
10cc0 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
10cd0 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
10ce0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
10cf0 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
10d00 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
10d10 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
10d20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
10d30 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
10d40 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
10d50 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
10d60 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
10d70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
10d80 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66  d..**.** The def
10d90 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
10da0 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
10db0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55  * The [SQLITE_BU
10dc0 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e  SY] error is con
10dd0 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54  verted to [SQLIT
10de0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
10df0 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
10e00 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  is in the middle
10e10 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e   of a large tran
10e20 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c  saction where al
10e30 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73  l the.** changes
10e40 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e   will not fit in
10e50 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  to the in-memory
10e60 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20   cache.  SQLite 
10e70 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20  will.** already 
10e80 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20  hold a RESERVED 
10e90 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61  lock on the data
10ea0 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69  base file, but i
10eb0 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72  t needs.** to pr
10ec0 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20  omote this lock 
10ed0 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20  to EXCLUSIVE so 
10ee0 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c  that it can spil
10ef0 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73  l cache.** pages
10f00 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
10f10 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20  se file without 
10f20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65  harm to concurre
10f30 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20  nt.** readers.  
10f40 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
10f50 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
10f60 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
10f70 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
10f80 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
10f90 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
10fa0 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
10fb0 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
10fc0 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
10fd0 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
10fe0 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
10ff0 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
11000 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
11010 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
11020 5d 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20 63  ].  This error c
11030 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a  ode promotion.**
11040 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d   forces an autom
11050 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66  atic rollback of
11060 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53   the changes.  S
11070 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65  ee the.** <a hre
11080 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69  f="/cvstrac/wiki
11090 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ?p=CorruptionFol
110a0 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22  lowingBusyError"
110b0 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46  >.** CorruptionF
110c0 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
110d0 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20  r</a> wiki page 
110e0 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e  for a discussion
110f0 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20   of why.** this 
11100 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a  is important..**
11110 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e  .** There can on
11120 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
11130 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
11140 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
11150 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11160 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
11170 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
11180 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
11190 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
111a0 68 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74  handler.  Note t
111b0 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
111c0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
111d0 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73  t()].** will als
111e0 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74  o set or clear t
111f0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
11200 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
11210 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 31  S:.**.** {H12311
11220 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
11230 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 43 2c  usy_handler(D,C,
11240 41 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61  A)] function sha
11250 6c 6c 20 72 65 70 6c 61 63 65 0a 2a 2a 20 20 20  ll replace.**   
11260 20 20 20 20 20 20 20 62 75 73 79 20 63 61 6c 6c         busy call
11270 62 61 63 6b 20 69 6e 20 74 68 65 20 5b 64 61 74  back in the [dat
11280 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11290 5d 20 44 20 77 69 74 68 20 61 20 6e 65 77 0a 2a  ] D with a new.*
112a0 2a 20 20 20 20 20 20 20 20 20 20 61 20 6e 65 77  *          a new
112b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 43 20   busy handler C 
112c0 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  and application 
112d0 64 61 74 61 20 70 6f 69 6e 74 65 72 20 41 2e 0a  data pointer A..
112e0 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 32 7d 20 4e  **.** {H12312} N
112f0 65 77 6c 79 20 63 72 65 61 74 65 64 20 5b 64 61  ewly created [da
11300 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11310 6e 73 5d 20 73 68 61 6c 6c 20 68 61 76 65 20 61  ns] shall have a
11320 20 62 75 73 79 0a 2a 2a 20 20 20 20 20 20 20 20   busy.**        
11330 20 20 68 61 6e 64 6c 65 72 20 6f 66 20 4e 55 4c    handler of NUL
11340 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 34  L..**.** {H12314
11350 7d 20 57 68 65 6e 20 74 77 6f 20 6f 72 20 6d 6f  } When two or mo
11360 72 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  re [database con
11370 6e 65 63 74 69 6f 6e 73 5d 20 73 68 61 72 65 20  nections] share 
11380 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  a.**          [s
11390 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
113a0 61 72 65 64 5f 63 61 63 68 65 20 7c 20 63 6f 6d  ared_cache | com
113b0 6d 6f 6e 20 63 61 63 68 65 5d 2c 0a 2a 2a 20 20  mon cache],.**  
113c0 20 20 20 20 20 20 20 20 74 68 65 20 62 75 73 79          the busy
113d0 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65   handler for the
113e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
113f0 74 69 6f 6e 20 63 75 72 72 65 6e 74 6c 79 20 75  tion currently u
11400 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  sing.**         
11410 20 74 68 65 20 63 61 63 68 65 20 73 68 61 6c 6c   the cache shall
11420 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
11430 20 74 68 65 20 63 61 63 68 65 20 65 6e 63 6f 75   the cache encou
11440 6e 74 65 72 73 20 61 20 6c 6f 63 6b 2e 0a 2a 2a  nters a lock..**
11450 0a 2a 2a 20 7b 48 31 32 33 31 36 7d 20 49 66 20  .** {H12316} If 
11460 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  a busy handler c
11470 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
11480 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 53  zero, then the S
11490 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
114a0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74  **          that
114b0 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20 6c 6f   provoked the lo
114c0 63 6b 69 6e 67 20 65 76 65 6e 74 20 73 68 61 6c  cking event shal
114d0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
114e0 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  _BUSY]..**.** {H
114f0 31 32 33 31 38 7d 20 53 51 4c 69 74 65 20 73 68  12318} SQLite sh
11500 61 6c 6c 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  all invokes the 
11510 62 75 73 79 20 68 61 6e 64 6c 65 72 20 77 69 74  busy handler wit
11520 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  h two arguments 
11530 77 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20 20  which.**        
11540 20 20 61 72 65 20 61 20 63 6f 70 79 20 6f 66 20    are a copy of 
11550 74 68 65 20 70 6f 69 6e 74 65 72 20 73 75 70 70  the pointer supp
11560 6c 69 65 64 20 62 79 20 74 68 65 20 33 72 64 20  lied by the 3rd 
11570 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
11580 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
11590 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
115a0 5d 20 61 6e 64 20 61 20 63 6f 75 6e 74 20 6f 66  ] and a count of
115b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
115c0 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  rior.**         
115d0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
115e0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
115f0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f   for the same lo
11600 63 6b 69 6e 67 20 65 76 65 6e 74 2e 0a 2a 2a 0a  cking event..**.
11610 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
11620 2a 2a 0a 2a 2a 20 7b 41 31 32 33 31 39 7d 20 41  **.** {A12319} A
11630 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75   busy handler mu
11640 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
11650 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
11660 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
11670 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74   or [prepared st
11680 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e  atement] that in
11690 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
116a0 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73  andler..*/.int s
116b0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
116c0 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
116d0 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c  t(*)(void*,int),
116e0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
116f0 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20  CAPI3REF: Set A 
11700 42 75 73 79 20 54 69 6d 65 6f 75 74 20 7b 48 31  Busy Timeout {H1
11710 32 33 34 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a  2340} <S40410>.*
11720 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
11730 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
11740 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
11750 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74   busy handler] t
11760 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f  hat sleeps.** fo
11770 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d  r a specified am
11780 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65  ount of time whe
11790 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  n a table is loc
117a0 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64 6c 65  ked.  The handle
117b0 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
117c0 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
117d0 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
117e0 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
117f0 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
11800 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
11810 20 7b 48 31 32 33 34 33 7d 20 41 66 74 65 72 20   {H12343} After 
11820 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
11830 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
11840 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
11850 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
11860 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
11870 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
11880 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
11890 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
118a0 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a  R_BLOCKED]..**.*
118b0 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72  * Calling this r
118c0 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
118d0 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
118e0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
118f0 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
11900 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
11910 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63  s..**.** There c
11920 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
11930 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
11940 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
11950 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
11960 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61  onnection] any a
11970 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
11980 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
11990 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
119a0 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
119b0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
119c0 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
119d0 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
119e0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
119f0 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
11a00 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
11a10 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
11a20 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34 31  S:.**.** {H12341
11a30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  } The [sqlite3_b
11a40 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 66  usy_timeout()] f
11a50 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 6f 76  unction shall ov
11a60 65 72 72 69 64 65 20 61 6e 79 20 70 72 69 6f 72  erride any prior
11a70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
11a80 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
11a90 75 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ut()] or [sqlite
11aa0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
11ab0 5d 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  ] setting.**    
11ac0 20 20 20 20 20 20 6f 6e 20 74 68 65 20 73 61 6d        on the sam
11ad0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
11ae0 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  ection]..**.** {
11af0 48 31 32 33 34 33 7d 20 49 66 20 74 68 65 20 32  H12343} If the 2
11b00 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
11b10 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
11b20 6d 65 6f 75 74 28 29 5d 20 69 73 20 6c 65 73 73  meout()] is less
11b30 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20   than.**        
11b40 20 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65    or equal to ze
11b50 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 62 75 73  ro, then the bus
11b60 79 20 68 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20  y handler shall 
11b70 62 65 20 63 6c 65 61 72 65 64 20 73 6f 20 74 68  be cleared so th
11b80 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  at.**          a
11b90 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 6c 6f  ll subsequent lo
11ba0 63 6b 69 6e 67 20 65 76 65 6e 74 73 20 69 6d 6d  cking events imm
11bb0 65 64 69 61 74 65 6c 79 20 72 65 74 75 72 6e 20  ediately return 
11bc0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
11bd0 2a 0a 2a 2a 20 7b 48 31 32 33 34 34 7d 20 49 66  *.** {H12344} If
11be0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
11bf0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
11c00 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69  usy_timeout()] i
11c10 73 20 61 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20  s a positive.** 
11c20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
11c30 4e 2c 20 74 68 65 6e 20 61 20 62 75 73 79 20 68  N, then a busy h
11c40 61 6e 64 6c 65 72 20 73 68 61 6c 6c 20 62 65 20  andler shall be 
11c50 73 65 74 20 74 68 61 74 20 72 65 70 65 61 74 65  set that repeate
11c60 64 6c 79 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20  dly calls.**    
11c70 20 20 20 20 20 20 74 68 65 20 78 53 6c 65 65 70        the xSleep
11c80 28 29 20 6d 65 74 68 6f 64 20 69 6e 20 74 68 65  () method in the
11c90 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
11ca0 56 46 53 20 69 6e 74 65 72 66 61 63 65 5d 20 75  VFS interface] u
11cb0 6e 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ntil.**         
11cc0 20 65 69 74 68 65 72 20 74 68 65 20 6c 6f 63 6b   either the lock
11cd0 20 63 6c 65 61 72 73 20 6f 72 20 75 6e 74 69 6c   clears or until
11ce0 20 74 68 65 20 63 75 6d 75 6c 61 74 69 76 65 20   the cumulative 
11cf0 73 6c 65 65 70 20 74 69 6d 65 0a 2a 2a 20 20 20  sleep time.**   
11d00 20 20 20 20 20 20 20 72 65 70 6f 72 74 65 64 20         reported 
11d10 62 61 63 6b 20 62 79 20 78 53 6c 65 65 70 28 29  back by xSleep()
11d20 20 65 78 63 65 65 64 73 20 4e 20 6d 69 6c 6c 69   exceeds N milli
11d30 73 65 63 6f 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20  seconds..*/.int 
11d40 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
11d50 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  eout(sqlite3*, i
11d60 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  nt ms);../*.** C
11d70 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69  API3REF: Conveni
11d80 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f  ence Routines Fo
11d90 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65  r Running Querie
11da0 73 20 7b 48 31 32 33 37 30 7d 20 3c 53 31 30 30  s {H12370} <S100
11db0 30 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  00>.**.** Defini
11dc0 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
11dd0 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
11de0 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
11df0 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
11e00 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
11e10 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
11e20 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
11e30 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
11e40 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
11e50 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
11e60 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
11e70 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
11e80 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
11e90 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
11ea0 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
11eb0 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
11ec0 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
11ed0 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
11ee0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
11ef0 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
11f00 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
11f10 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
11f20 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
11f30 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
11f40 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
11f50 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
11f60 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
11f70 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
11f80 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
11f90 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
11fa0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
11fb0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
11fc0 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
11fd0 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
11fe0 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
11ff0 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
12000 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
12010 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
12020 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
12030 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
12040 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
12050 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
12060 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
12070 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
12080 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
12090 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
120a0 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
120b0 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
120c0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
120d0 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
120e0 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
120f0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
12100 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
12110 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
12120 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
12130 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
12140 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
12150 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
12160 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
12170 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
12180 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
12190 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
121a0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
121b0 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
121c0 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
121d0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
121e0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e  ()]..**.** As an
121f0 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
12200 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
12210 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
12220 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
12230 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
12240 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
12250 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
12260 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
12270 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
12280 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
12290 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
122a0 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
122b0 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
122c0 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
122d0 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
122e0 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
122f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
12300 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
12310 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
12320 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
12330 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
12340 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
12350 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
12360 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
12370 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
12380 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
12390 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
123a0 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
123b0 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
123c0 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
123d0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
123e0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
123f0 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
12400 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
12410 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
12420 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
12430 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
12440 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
12450 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
12460 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
12470 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
12480 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
12490 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
124a0 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
124b0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
124c0 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
124d0 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
124e0 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
124f0 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
12500 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
12510 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
12520 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74  et_table() funct
12530 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e  ion evaluates on
12540 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d  e or more.** sem
12550 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64  icolon-separated
12560 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
12570 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  in the zero-term
12580 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
12590 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e  string of its 2n
125a0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 74  d parameter.  It
125b0 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
125c0 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
125d0 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
125e0 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
125f0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
12600 72 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  r the calling fu
12610 6e 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  nction has finis
12620 68 65 64 20 75 73 69 6e 67 20 74 68 65 20 72 65  hed using the re
12630 73 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 0a  sult, it should.
12640 2a 2a 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  ** pass the poin
12650 74 65 72 20 74 6f 20 74 68 65 20 72 65 73 75 6c  ter to the resul
12660 74 20 74 61 62 6c 65 20 74 6f 20 73 71 6c 69 74  t table to sqlit
12670 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
12680 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
12690 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
126a0 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
126b0 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
126c0 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
126d0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
126e0 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
126f0 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
12700 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
12710 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
12720 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
12730 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
12740 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
12750 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
12760 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
12770 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
12780 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
12790 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
127a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
127b0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
127c0 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
127d0 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
127e0 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
127f0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
12800 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
12810 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
12820 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
12830 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
12840 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
12850 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
12860 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
12870 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
12880 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
12890 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
128a0 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
128b0 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
128c0 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
128d0 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
128e0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
128f0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
12900 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
12910 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
12920 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
12930 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
12940 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
12950 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a  _errmsg()]..**.*
12960 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
12970 0a 2a 2a 20 7b 48 31 32 33 37 31 7d 20 49 66 20  .** {H12371} If 
12980 61 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  a [sqlite3_get_t
12990 61 62 6c 65 28 29 5d 20 66 61 69 6c 73 20 61 20  able()] fails a 
129a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
129b0 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  n, then.**      
129c0 20 20 20 20 69 74 20 73 68 61 6c 6c 20 66 72 65      it shall fre
129d0 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
129e0 6c 65 20 75 6e 64 65 72 20 63 6f 6e 73 74 72 75  le under constru
129f0 63 74 69 6f 6e 2c 20 61 62 6f 72 74 20 74 68 65  ction, abort the
12a00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 71 75 65  .**          que
12a10 72 79 20 69 6e 20 70 72 6f 63 65 73 73 2c 20 73  ry in process, s
12a20 6b 69 70 20 61 6e 79 20 73 75 62 73 65 71 75 65  kip any subseque
12a30 6e 74 20 71 75 65 72 69 65 73 2c 20 73 65 74 20  nt queries, set 
12a40 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
12a50 2a 70 61 7a 52 65 73 75 6c 74 20 6f 75 74 70 75  *pazResult outpu
12a60 74 20 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c  t pointer to NUL
12a70 4c 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  L and return [SQ
12a80 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
12a90 2a 2a 20 7b 48 31 32 33 37 33 7d 20 49 66 20 74  ** {H12373} If t
12aa0 68 65 20 70 6e 43 6f 6c 75 6d 6e 20 70 61 72 61  he pnColumn para
12ab0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
12ac0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
12ad0 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20  s not NULL.**   
12ae0 20 20 20 20 20 20 20 74 68 65 6e 20 61 20 73 75         then a su
12af0 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
12b00 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
12b10 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 73 68 61  get_table()] sha
12b20 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  ll.**          w
12b30 72 69 74 65 20 74 68 65 20 6e 75 6d 62 65 72 20  rite the number 
12b40 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
12b50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
12b60 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20  sult set of the 
12b70 71 75 65 72 79 20 69 6e 74 6f 20 2a 70 6e 43 6f  query into *pnCo
12b80 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  lumn..**.** {H12
12b90 33 37 34 7d 20 49 66 20 74 68 65 20 70 6e 52 6f  374} If the pnRo
12ba0 77 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  w parameter to [
12bb0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
12bc0 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  e()] is not NULL
12bd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
12be0 6e 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 69  n a successful i
12bf0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
12c00 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
12c10 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20  )] shall.**     
12c20 20 20 20 20 20 77 72 69 74 65 73 20 74 68 65 20       writes the 
12c30 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69  number of rows i
12c40 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
12c50 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20    result set of 
12c60 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f 20 2a  the query into *
12c70 70 6e 52 6f 77 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  pnRow..**.** {H1
12c80 32 33 37 36 7d 20 41 20 73 75 63 63 65 73 73 66  2376} A successf
12c90 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
12ca0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
12cb0 62 6c 65 28 29 5d 20 74 68 61 74 20 63 6f 6d 70  ble()] that comp
12cc0 75 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  utes.**         
12cd0 20 4e 20 72 6f 77 73 20 6f 66 20 72 65 73 75 6c   N rows of resul
12ce0 74 20 77 69 74 68 20 43 20 63 6f 6c 75 6d 6e 73  t with C columns
12cf0 20 70 65 72 20 72 6f 77 20 73 68 61 6c 6c 20 6d   per row shall m
12d00 61 6b 65 20 2a 70 61 7a 52 65 73 75 6c 74 0a 2a  ake *pazResult.*
12d10 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
12d20 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20   to an array of 
12d30 70 6f 69 6e 74 65 72 73 20 74 6f 20 28 4e 2b 31  pointers to (N+1
12d40 29 2a 43 20 73 74 72 69 6e 67 73 20 77 68 65 72  )*C strings wher
12d50 65 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 20  e the first.**  
12d60 20 20 20 20 20 20 20 20 43 20 73 74 72 69 6e 67          C string
12d70 73 20 61 72 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  s are column nam
12d80 65 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20 66  es as obtained f
12d90 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rom.**          
12da0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
12db0 6e 61 6d 65 28 29 5d 20 61 6e 64 20 74 68 65 20  name()] and the 
12dc0 72 65 73 74 20 61 72 65 20 63 6f 6c 75 6d 6e 20  rest are column 
12dd0 72 65 73 75 6c 74 20 76 61 6c 75 65 73 0a 2a 2a  result values.**
12de0 20 20 20 20 20 20 20 20 20 20 6f 62 74 61 69 6e            obtain
12df0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
12e00 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
12e10 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 39 7d 20  .**.** {H12379} 
12e20 54 68 65 20 76 61 6c 75 65 73 20 69 6e 20 74 68  The values in th
12e30 65 20 70 61 7a 52 65 73 75 6c 74 20 61 72 72 61  e pazResult arra
12e40 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  y returned by [s
12e50 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
12e60 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
12e70 73 68 61 6c 6c 20 72 65 6d 61 69 6e 20 76 61 6c  shall remain val
12e80 69 64 20 75 6e 74 69 6c 20 63 6c 65 61 72 65 64  id until cleared
12e90 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
12ea0 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
12eb0 2a 20 7b 48 31 32 33 38 32 7d 20 57 68 65 6e 20  * {H12382} When 
12ec0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
12ed0 64 75 72 69 6e 67 20 65 76 61 6c 75 61 74 69 6f  during evaluatio
12ee0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65  n of [sqlite3_ge
12ef0 74 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20  t_table()].**   
12f00 20 20 20 20 20 20 20 74 68 65 20 66 75 6e 63 74         the funct
12f10 69 6f 6e 20 73 68 61 6c 6c 20 73 65 74 20 2a 70  ion shall set *p
12f20 61 7a 52 65 73 75 6c 74 20 74 6f 20 4e 55 4c 4c  azResult to NULL
12f30 2c 20 77 72 69 74 65 20 61 6e 20 65 72 72 6f 72  , write an error
12f40 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20 20   message.**     
12f50 20 20 20 20 20 69 6e 74 6f 20 6d 65 6d 6f 72 79       into memory
12f60 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
12f70 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
12f80 5d 2c 20 6d 61 6b 65 0a 2a 2a 20 20 20 20 20 20  ], make.**      
12f90 20 20 20 20 2a 2a 70 7a 45 72 72 6d 73 67 20 70      **pzErrmsg p
12fa0 6f 69 6e 74 20 74 6f 20 74 68 61 74 20 65 72 72  oint to that err
12fb0 6f 72 20 6d 65 73 73 61 67 65 2c 20 61 6e 64 20  or message, and 
12fc0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 20 20 20 20  return a.**     
12fd0 20 20 20 20 20 61 70 70 72 6f 70 72 69 61 74 65       appropriate
12fe0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
12ff0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
13000 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
13010 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
13020 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
13030 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
13040 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
13050 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
13060 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
13070 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
13080 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
13090 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
130a0 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
130b0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
130c0 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
130d0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
130e0 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
130f0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
13100 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
13110 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
13120 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
13130 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
13140 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
13150 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
13160 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
13170 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
13180 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13190 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
131a0 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
131b0 63 74 69 6f 6e 73 20 7b 48 31 37 34 30 30 7d 20  ctions {H17400} 
131c0 3c 53 37 30 30 30 30 3e 3c 53 32 30 30 30 30 3e  <S70000><S20000>
131d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
131e0 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 61 6c  tines are workal
131f0 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69  ikes of the "pri
13200 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66  ntf()" family of
13210 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72   functions.** fr
13220 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
13230 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  C library..**.**
13240 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72   The sqlite3_mpr
13250 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
13260 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
13270 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
13280 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
13290 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
132a0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
132b0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
132c0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
132d0 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
132e0 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
132f0 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
13300 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
13310 28 29 5d 2e 20 20 42 6f 74 68 20 72 6f 75 74 69  ()].  Both routi
13320 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  nes return a.** 
13330 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
13340 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13350 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  )] is unable to 
13360 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a  allocate enough.
13370 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** memory to hol
13380 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  d the resulting 
13390 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e  string..**.** In
133a0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
133b0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
133c0 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
133d0 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
133e0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
133f0 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
13400 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
13410 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
13420 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
13430 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
13440 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
13450 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
13460 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
13470 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
13480 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
13490 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
134a0 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
134b0 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
134c0 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
134d0 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
134e0 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
134f0 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
13500 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
13510 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
13520 6c 69 74 79 2e 20 20 4e 6f 74 65 20 61 6c 73 6f  lity.  Note also
13530 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
13540 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
13550 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
13560 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
13570 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
13580 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
13590 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
135a0 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
135b0 66 65 72 2e 20 20 57 65 20 61 64 6d 69 74 20 74  fer.  We admit t
135c0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
135d0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
135e0 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
135f0 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
13600 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
13610 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
13620 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
13630 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
13640 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
13650 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
13660 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
13670 74 79 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 6c 6f 6e  ty..**.** As lon
13680 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
13690 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
136a0 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
136b0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
136c0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
136d0 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
136e0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
136f0 6e 61 74 65 64 2e 20 20 54 68 65 20 66 69 72 73  nated.  The firs
13700 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
13710 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
13720 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
13730 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
13740 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
13750 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
13760 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
13770 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
13780 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
13790 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
137a0 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
137b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
137c0 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
137d0 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
137e0 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
137f0 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
13800 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
13810 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
13820 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
13830 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
13840 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
13850 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
13860 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
13870 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
13880 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20  "%q", "%Q", and 
13890 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a  "%z" options..**
138a0 0a 2a 2a 20 54 68 65 20 25 71 20 6f 70 74 69 6f  .** The %q optio
138b0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
138c0 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
138d0 69 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65  itutes a null-te
138e0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
138f0 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
13900 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
13910 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
13920 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
13930 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
13940 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
13950 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
13960 6c 69 74 65 72 61 6c 2e 20 20 42 79 20 64 6f 75  literal.  By dou
13970 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
13980 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
13990 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
139a0 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
139b0 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
139c0 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
139d0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
139e0 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
139f0 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
13a00 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
13a10 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
13a20 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
13a30 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
13a40 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
13a50 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
13a60 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
13a70 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
13a80 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
13a90 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
13aa0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
13ab0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
13ac0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
13ad0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
13ae0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
13af0 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
13b00 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
13b10 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
13b20 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
13b30 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
13b40 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
13b50 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
13b60 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
13b70 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
13b80 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
13b90 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
13ba0 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
13bb0 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
13bc0 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
13bd0 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
13be0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
13bf0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
13c00 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
13c10 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
13c20 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
13c30 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
13c40 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
13c50 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
13c60 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
13c70 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
13c80 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
13c90 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
13ca0 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
13cb0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
13cc0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
13cd0 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
13ce0 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
13cf0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
13d00 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
13d10 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
13d20 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
13d30 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
13d40 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
13d50 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
13d60 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
13d70 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
13d80 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
13d90 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
13da0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
13db0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 51 20 6f  ..**.** The %Q o
13dc0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
13dd0 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
13de0 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
13df0 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
13e00 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
13e10 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
13e20 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
13e30 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
13e40 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
13e50 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
13e60 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
13e70 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
13e80 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
13e90 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
13ea0 6f 74 65 73 29 20 69 6e 20 70 6c 61 63 65 20 6f  otes) in place o
13eb0 66 20 74 68 65 20 25 51 20 6f 70 74 69 6f 6e 2e  f the %Q option.
13ec0 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
13ed0 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
13ee0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
13ef0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
13f00 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
13f10 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
13f20 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
13f30 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
13f40 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
13f50 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
13f60 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
13f70 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
13f80 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
13f90 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
13fa0 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
13fb0 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
13fc0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
13fd0 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
13fe0 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
13ff0 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
14000 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
14010 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
14020 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
14030 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 65 78 61  option works exa
14040 63 74 6c 79 20 6c 69 6b 65 20 22 25 73 22 20 77  ctly like "%s" w
14050 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
14060 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
14070 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
14080 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
14090 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
140a0 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
140b0 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
140c0 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
140d0 74 72 69 6e 67 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  tring. {END}.**.
140e0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
140f0 2a 0a 2a 2a 20 7b 48 31 37 34 30 33 7d 20 20 54  *.** {H17403}  T
14100 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69  he [sqlite3_mpri
14110 6e 74 66 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ntf()] and [sqli
14120 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 5d 20  te3_vmprintf()] 
14130 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 20 20  interfaces.**   
14140 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 65          return e
14150 69 74 68 65 72 20 70 6f 69 6e 74 65 72 73 20 74  ither pointers t
14160 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
14170 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 20  d UTF-8 strings 
14180 68 65 6c 64 20 69 6e 0a 2a 2a 20 20 20 20 20 20  held in.**      
14190 20 20 20 20 20 6d 65 6d 6f 72 79 20 6f 62 74 61       memory obta
141a0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
141b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
141c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 69 66  NULL pointers if
141d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20  .**           a 
141e0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
141f0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 61 69 6c 73  _malloc()] fails
14200 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 36 7d  ..**.** {H17406}
14210 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73    The [sqlite3_s
14220 6e 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72  nprintf()] inter
14230 66 61 63 65 20 77 72 69 74 65 73 20 61 20 7a 65  face writes a ze
14240 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
14250 20 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38             UTF-8
14260 20 73 74 72 69 6e 67 20 69 6e 74 6f 20 74 68 65   string into the
14270 20 62 75 66 66 65 72 20 70 6f 69 6e 74 65 64 20   buffer pointed 
14280 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
14290 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
142a0 20 20 20 20 20 20 20 20 70 72 6f 76 69 64 65 64          provided
142b0 20 74 68 61 74 20 74 68 65 20 66 69 72 73 74 20   that the first 
142c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 67 72 65  parameter is gre
142d0 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2e 0a  ater than zero..
142e0 2a 2a 0a 2a 2a 20 7b 48 31 37 34 30 37 7d 20 20  **.** {H17407}  
142f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  The [sqlite3_snp
14300 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72 66 61  rintf()] interfa
14310 63 65 20 64 6f 65 73 20 6e 6f 74 20 77 72 69 74  ce does not writ
14320 65 20 73 6c 6f 74 73 20 6f 66 0a 2a 2a 20 20 20  e slots of.**   
14330 20 20 20 20 20 20 20 20 69 74 73 20 6f 75 74 70          its outp
14340 75 74 20 62 75 66 66 65 72 20 28 74 68 65 20 73  ut buffer (the s
14350 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 29  econd parameter)
14360 20 6f 75 74 73 69 64 65 20 74 68 65 20 72 61 6e   outside the ran
14370 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ge.**           
14380 6f 66 20 30 20 74 68 72 6f 75 67 68 20 4e 2d 31  of 0 through N-1
14390 20 28 77 68 65 72 65 20 4e 20 69 73 20 74 68 65   (where N is the
143a0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
143b0 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72  ).**           r
143c0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
143d0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
143e0 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  tring.**        
143f0 20 20 20 72 65 71 75 65 73 74 65 64 20 62 79 20     requested by 
14400 74 68 65 20 66 6f 72 6d 61 74 20 73 70 65 63 69  the format speci
14410 66 69 63 61 74 69 6f 6e 2e 0a 2a 2f 0a 63 68 61  fication..*/.cha
14420 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
14430 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
14440 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
14450 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
14460 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
14470 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
14480 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
14490 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
144a0 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
144b0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
144c0 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
144d0 74 65 6d 20 7b 48 31 37 33 30 30 7d 20 3c 53 32  tem {H17300} <S2
144e0 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0000>.**.** The 
144f0 53 51 4c 69 74 65 20 63 6f 72 65 20 20 75 73 65  SQLite core  use
14500 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f  s these three ro
14510 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f  utines for all o
14520 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74  f its own.** int
14530 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ernal memory all
14540 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22  ocation needs. "
14550 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65  Core" in the pre
14560 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a  vious sentence.*
14570 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  * does not inclu
14580 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  de operating-sys
14590 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
145a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
145b0 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73    The.** Windows
145c0 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65   VFS uses native
145d0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
145e0 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70  ee() for some op
145f0 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
14600 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
14610 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
14620 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
14630 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
14640 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
14650 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
14660 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
14670 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
14680 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
14690 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
146a0 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
146b0 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
146c0 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
146d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49  NULL pointer.  I
146e0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
146f0 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
14700 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
14710 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
14720 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
14730 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
14740 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
14750 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69  .** Calling sqli
14760 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
14770 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
14780 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
14790 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
147a0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
147b0 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
147c0 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
147d0 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
147e0 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 54  ht be reused.  T
147f0 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
14800 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
14810 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
14820 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
14830 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
14840 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
14850 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
14860 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
14870 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
14880 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
14890 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
148a0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
148b0 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
148c0 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
148d0 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
148e0 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
148f0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
14900 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
14910 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
14920 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
14930 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
14940 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
14950 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
14960 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
14970 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
14980 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
14990 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
149a0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
149b0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
149c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
149d0 6f 72 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  or sqlite3_free(
149e0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
149f0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
14a00 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
14a10 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a  s to resize a.**
14a20 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c   prior memory al
14a30 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61  location to be a
14a40 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c  t least N bytes,
14a50 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
14a60 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
14a70 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79  ter.  The memory
14a80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62   allocation to b
14a90 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65  e resized is the
14aa0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
14ab0 74 65 72 2e 20 20 49 66 20 74 68 65 20 66 69 72  ter.  If the fir
14ac0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
14ad0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
14ae0 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
14af0 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
14b00 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
14b10 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
14b20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
14b30 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73  oc(N) where N is
14b40 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
14b50 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
14b60 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49  _realloc()..** I
14b70 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  f the second par
14b80 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
14b90 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a  3_realloc() is z
14ba0 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
14bb0 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
14bc0 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
14bd0 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
14be0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
14bf0 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69  ree(P) where P i
14c00 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
14c10 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
14c20 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 73  _realloc()..** s
14c30 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
14c40 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
14c50 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61  er to a memory a
14c60 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
14c70 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
14c80 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c   in size or NULL
14c90 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d   if sufficient m
14ca0 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c  emory is unavail
14cb0 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73  able..** If M is
14cc0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
14cd0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
14ce0 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29  n, then min(N,M)
14cf0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65   bytes.** of the
14d00 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
14d10 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  n are copied int
14d20 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
14d30 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e  of buffer return
14d40 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
14d50 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74  _realloc() and t
14d60 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
14d70 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
14d80 20 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   If sqlite3_real
14d90 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55  loc() returns NU
14da0 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69  LL, then the pri
14db0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  or allocation.**
14dc0 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
14dd0 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20  *.** The memory 
14de0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
14df0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  te3_malloc() and
14e00 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
14e10 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ().** is always 
14e20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65  aligned to at le
14e30 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f  ast an 8 byte bo
14e40 75 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a  undary. {END}.**
14e50 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
14e60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
14e70 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  f the memory all
14e80 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
14e90 6d 20 75 73 65 73 0a 2a 2a 20 74 68 65 20 6d 61  m uses.** the ma
14ea0 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28  lloc(), realloc(
14eb0 29 20 61 6e 64 20 66 72 65 65 28 29 20 70 72 6f  ) and free() pro
14ec0 76 69 64 65 64 20 62 79 20 74 68 65 20 73 74 61  vided by the sta
14ed0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
14ee0 0a 2a 2a 20 7b 48 31 37 33 38 32 7d 20 48 6f 77  .** {H17382} How
14ef0 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20  ever, if SQLite 
14f00 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
14f10 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d   the.** SQLITE_M
14f20 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e  EMORY_SIZE=<i>NN
14f30 4e 3c 2f 69 3e 20 43 20 70 72 65 70 72 6f 63 65  N</i> C preproce
14f40 73 73 6f 72 20 6d 61 63 72 6f 20 28 77 68 65 72  ssor macro (wher
14f50 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20  e <i>NNN</i>.** 
14f60 69 73 20 61 6e 20 69 6e 74 65 67 65 72 29 2c 20  is an integer), 
14f70 74 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65 61  then SQLite crea
14f80 74 65 20 61 20 73 74 61 74 69 63 20 61 72 72 61  te a static arra
14f90 79 20 6f 66 20 61 74 20 6c 65 61 73 74 0a 2a 2a  y of at least.**
14fa0 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65   <i>NNN</i> byte
14fb0 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 73  s in size and us
14fc0 65 73 20 74 68 61 74 20 61 72 72 61 79 20 66 6f  es that array fo
14fd0 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e  r all of its dyn
14fe0 61 6d 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  amic.** memory a
14ff0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
15000 20 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e   {END}  Addition
15010 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
15020 74 6f 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 6d  tor options.** m
15030 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
15040 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
15050 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
15060 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
15070 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
15080 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
15090 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
150a0 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
150b0 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
150c0 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
150d0 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
150e0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
150f0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
15100 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
15110 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
15120 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
15130 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
15140 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
15150 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65  ators can be use
15160 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e  d..**.** The Win
15170 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
15180 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a  e layer calls.**
15190 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
151a0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
151b0 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
151c0 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
151d0 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
151e0 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
151f0 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
15200 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
15210 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
15220 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
15230 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
15240 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
15250 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
15260 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61  ocation errors a
15270 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
15280 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70  .** they are rep
15290 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
152a0 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
152b0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
152c0 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
152d0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
152e0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
152f0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 33  S:.**.** {H17303
15300 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
15310 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72  malloc(N)] inter
15320 66 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74  face returns eit
15330 68 65 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  her a pointer to
15340 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20  .**           a 
15350 6e 65 77 6c 79 20 63 68 65 63 6b 65 64 2d 6f 75  newly checked-ou
15360 74 20 62 6c 6f 63 6b 20 6f 66 20 61 74 20 6c 65  t block of at le
15370 61 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 6d  ast N bytes of m
15380 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20  emory.**        
15390 20 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 74     that is 8-byt
153a0 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 69 74  e aligned, or it
153b0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66   returns NULL if
153c0 20 69 74 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a   it is unable.**
153d0 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 66 75             to fu
153e0 6c 66 69 6c 6c 20 74 68 65 20 72 65 71 75 65 73  lfill the reques
153f0 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 34  t..**.** {H17304
15400 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
15410 6d 61 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72  malloc(N)] inter
15420 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 4e  face returns a N
15430 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 0a 2a  ULL pointer if.*
15440 2a 20 20 20 20 20 20 20 20 20 20 20 4e 20 69 73  *           N is
15450 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
15460 75 61 6c 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  ual to zero..**.
15470 2a 2a 20 7b 48 31 37 33 30 35 7d 20 20 54 68 65  ** {H17305}  The
15480 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50   [sqlite3_free(P
15490 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 6c  )] interface rel
154a0 65 61 73 65 73 20 6d 65 6d 6f 72 79 20 70 72 65  eases memory pre
154b0 76 69 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20  viously.**      
154c0 20 20 20 20 20 72 65 74 75 72 6e 65 64 20 66 72       returned fr
154d0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
154e0 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
154f0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  3_realloc()],.**
15500 20 20 20 20 20 20 20 20 20 20 20 6d 61 6b 69 6e             makin
15510 67 20 69 74 20 61 76 61 69 6c 61 62 6c 65 20 66  g it available f
15520 6f 72 20 72 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20  or reuse..**.** 
15530 7b 48 31 37 33 30 36 7d 20 20 41 20 63 61 6c 6c  {H17306}  A call
15540 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
15550 65 28 4e 55 4c 4c 29 5d 20 69 73 20 61 20 68 61  e(NULL)] is a ha
15560 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
15570 0a 2a 2a 20 7b 48 31 37 33 31 30 7d 20 20 41 20  .** {H17310}  A 
15580 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
15590 5f 72 65 61 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69  _realloc(0,N)] i
155a0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
155b0 61 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20  a call.**       
155c0 20 20 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f      to [sqlite3_
155d0 6d 61 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a  malloc(N)]..**.*
155e0 2a 20 7b 48 31 37 33 31 32 7d 20 20 41 20 63 61  * {H17312}  A ca
155f0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
15600 65 61 6c 6c 6f 63 28 50 2c 30 29 5d 20 69 73 20  ealloc(P,0)] is 
15610 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20  equivalent to a 
15620 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  call.**         
15630 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72    to [sqlite3_fr
15640 65 65 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ee(P)]..**.** {H
15650 31 37 33 31 35 7d 20 20 54 68 65 20 53 51 4c 69  17315}  The SQLi
15660 74 65 20 63 6f 72 65 20 75 73 65 73 20 5b 73 71  te core uses [sq
15670 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
15680 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
15690 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  c()],.**        
156a0 20 20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f     and [sqlite3_
156b0 66 72 65 65 28 29 5d 20 66 6f 72 20 61 6c 6c 20  free()] for all 
156c0 6f 66 20 69 74 73 20 6d 65 6d 6f 72 79 20 61 6c  of its memory al
156d0 6c 6f 63 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  location and.** 
156e0 20 20 20 20 20 20 20 20 20 20 64 65 61 6c 6c 6f            deallo
156f0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
15700 0a 2a 2a 20 7b 48 31 37 33 31 38 7d 20 20 54 68  .** {H17318}  Th
15710 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  e [sqlite3_reall
15720 6f 63 28 50 2c 4e 29 5d 20 69 6e 74 65 72 66 61  oc(P,N)] interfa
15730 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
15740 72 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20  r a pointer.**  
15750 20 20 20 20 20 20 20 20 20 74 6f 20 61 20 62 6c           to a bl
15760 6f 63 6b 20 6f 66 20 63 68 65 63 6b 65 64 2d 6f  ock of checked-o
15770 75 74 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20  ut memory of at 
15780 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
15790 20 73 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20   size.**        
157a0 20 20 20 74 68 61 74 20 69 73 20 38 2d 62 79 74     that is 8-byt
157b0 65 20 61 6c 69 67 6e 65 64 2c 20 6f 72 20 61 20  e aligned, or a 
157c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
157d0 0a 2a 2a 20 7b 48 31 37 33 32 31 7d 20 20 57 68  .** {H17321}  Wh
157e0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  en [sqlite3_real
157f0 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e  loc(P,N)] return
15800 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
15810 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a  nter, it first.*
15820 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f 70 69  *           copi
15830 65 73 20 74 68 65 20 66 69 72 73 74 20 4b 20 62  es the first K b
15840 79 74 65 73 20 6f 66 20 63 6f 6e 74 65 6e 74 20  ytes of content 
15850 66 72 6f 6d 20 50 20 69 6e 74 6f 20 74 68 65 20  from P into the 
15860 6e 65 77 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  newly.**        
15870 20 20 20 61 6c 6c 6f 63 61 74 65 64 20 62 6c 6f     allocated blo
15880 63 6b 2c 20 77 68 65 72 65 20 4b 20 69 73 20 74  ck, where K is t
15890 68 65 20 6c 65 73 73 65 72 20 6f 66 20 4e 20 61  he lesser of N a
158a0 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a  nd the size of.*
158b0 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20  *           the 
158c0 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20  buffer P..**.** 
158d0 7b 48 31 37 33 32 32 7d 20 20 57 68 65 6e 20 5b  {H17322}  When [
158e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
158f0 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20  P,N)] returns a 
15900 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
15910 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20  , it first.**   
15920 20 20 20 20 20 20 20 20 72 65 6c 65 61 73 65 73          releases
15930 20 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a   the buffer P..*
15940 2a 0a 2a 2a 20 7b 48 31 37 33 32 33 7d 20 20 57  *.** {H17323}  W
15950 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  hen [sqlite3_rea
15960 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72  lloc(P,N)] retur
15970 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 20 62 75 66  ns NULL, the buf
15980 66 65 72 20 50 20 69 73 0a 2a 2a 20 20 20 20 20  fer P is.**     
15990 20 20 20 20 20 20 6e 6f 74 20 6d 6f 64 69 66 69        not modifi
159a0 65 64 20 6f 72 20 72 65 6c 65 61 73 65 64 2e 0a  ed or released..
159b0 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e  **.** ASSUMPTION
159c0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 30  S:.**.** {A17350
159d0 7d 20 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61  }  The pointer a
159e0 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c  rguments to [sql
159f0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64  ite3_free()] and
15a00 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
15a10 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  c()].**         
15a20 20 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72    must be either
15a30 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
15a40 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
15a50 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
15a60 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61            invoca
15a70 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
15a80 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
15a90 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
15aa0 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 20  ] that have.**  
15ab0 20 20 20 20 20 20 20 20 20 6e 6f 74 20 79 65 74           not yet
15ac0 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a   been released..
15ad0 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 31 7d 20 20  **.** {A17351}  
15ae0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
15af0 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
15b00 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
15b10 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  of.**           
15b20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
15b30 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
15b40 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
15b50 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ng.**           
15b60 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
15b70 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
15b80 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  lloc()]..*/.void
15b90 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
15ba0 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  (int);.void *sql
15bb0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
15bc0 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
15bd0 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
15be0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
15bf0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
15c00 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
15c10 20 7b 48 31 37 33 37 30 7d 20 3c 53 33 30 32 31   {H17370} <S3021
15c20 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  0>.**.** SQLite 
15c30 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
15c40 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
15c50 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
15c60 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
15c70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
15c80 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
15c90 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
15ca0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
15cb0 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
15cc0 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
15cd0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
15ce0 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
15cf0 65 6d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  em..**.** INVARI
15d00 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  ANTS:.**.** {H17
15d10 33 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  371} The [sqlite
15d20 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
15d30 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
15d40 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
15d50 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ytes.**         
15d60 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
15d70 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
15d80 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
15d90 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a  ot freed)..**.**
15da0 20 7b 48 31 37 33 37 33 7d 20 54 68 65 20 5b 73   {H17373} The [s
15db0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
15dc0 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69  ghwater()] routi
15dd0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d  ne returns the m
15de0 61 78 69 6d 75 6d 0a 2a 2a 20 20 20 20 20 20 20  aximum.**       
15df0 20 20 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c     value of [sql
15e00 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
15e10 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69  ()] since the hi
15e20 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
15e30 20 20 20 20 20 20 20 20 20 20 77 61 73 20 6c 61            was la
15e40 73 74 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  st reset..**.** 
15e50 7b 48 31 37 33 37 34 7d 20 54 68 65 20 76 61 6c  {H17374} The val
15e60 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
15e70 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
15e80 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20  used()] and.**  
15e90 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
15ea0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
15eb0 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
15ec0 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 20 20 20   overhead.**    
15ed0 20 20 20 20 20 20 61 64 64 65 64 20 62 79 20 53        added by S
15ee0 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70  QLite in its imp
15ef0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
15f00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
15f10 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  ],.**          b
15f20 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
15f30 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
15f40 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
15f50 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 20 20  em library.**   
15f60 20 20 20 20 20 20 20 72 6f 75 74 69 6e 65 73 20         routines 
15f70 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
15f80 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
15f90 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 35 7d  ..**.** {H17375}
15fa0 20 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68   The memory high
15fb0 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
15fc0 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
15fd0 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
15fe0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
15ff0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
16000 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
16010 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
16020 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
16030 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
16040 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
16050 65 2e 20 20 54 68 65 20 76 61 6c 75 65 20 72 65  e.  The value re
16060 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20  turned.**       
16070 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d     by [sqlite3_m
16080 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
16090 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
160a0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20  water mark.**   
160b0 20 20 20 20 20 20 20 70 72 69 6f 72 20 74 6f 20         prior to 
160c0 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71  the reset..*/.sq
160d0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
160e0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
160f0 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69  void);.sqlite3_i
16100 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
16110 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
16120 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
16130 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
16140 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
16150 62 65 72 20 47 65 6e 65 72 61 74 6f 72 20 7b 48  ber Generator {H
16160 31 37 33 39 30 7d 20 3c 53 32 30 30 30 30 3e 0a  17390} <S20000>.
16170 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e  **.** SQLite con
16180 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61  tains a high-qua
16190 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64  lity pseudo-rand
161a0 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61  om number genera
161b0 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20  tor (PRNG) used 
161c0 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e  to.** select ran
161d0 64 6f 6d 20 52 4f 57 49 44 73 20 77 68 65 6e 20  dom ROWIDs when 
161e0 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
161f0 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
16200 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
16210 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
16220 65 73 74 20 70 6f 73 73 69 62 6c 65 20 52 4f 57  est possible ROW
16230 49 44 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  ID.  The PRNG is
16240 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
16250 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
16260 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
16270 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
16280 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
16290 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
162a0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
162b0 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
162c0 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
162d0 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
162e0 20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20   A call to this 
162f0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
16300 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
16310 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
16320 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69   P..**.** The fi
16330 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f  rst time this ro
16340 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64  utine is invoked
16350 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61   (either interna
16360 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65  lly or by.** the
16370 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68   application) th
16380 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64  e PRNG is seeded
16390 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
163a0 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  s obtained.** fr
163b0 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
163c0 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ss method of the
163d0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
163e0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
163f0 2a 20 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75  * On all subsequ
16400 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c  ent invocations,
16410 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
16420 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
16430 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
16440 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
16450 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
16460 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
16470 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
16480 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  d..**.** INVARIA
16490 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  NTS:.**.** {H173
164a0 39 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  92} The [sqlite3
164b0 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 4e 2c 50 29  _randomness(N,P)
164c0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 72 69 74  ] interface writ
164d0 65 73 20 4e 20 62 79 74 65 73 20 6f 66 0a 2a 2a  es N bytes of.**
164e0 20 20 20 20 20 20 20 20 20 20 68 69 67 68 2d 71            high-q
164f0 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61  uality pseudo-ra
16500 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
16510 66 66 65 72 20 50 2e 0a 2a 2f 0a 76 6f 69 64 20  ffer P..*/.void 
16520 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
16530 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
16540 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
16550 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
16560 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
16570 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 35 30  Callbacks {H1250
16580 30 7d 20 3c 53 37 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S70100>.**.*
16590 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
165a0 65 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f  egisters a autho
165b0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
165c0 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
165d0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
165e0 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
165f0 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
16600 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
16610 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16620 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
16630 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
16640 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
16650 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
16660 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
16670 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
16680 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
16690 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
166a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
166b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
166c0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
166d0 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
166e0 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
166f0 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
16700 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
16710 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
16720 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
16730 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
16740 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16750 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
16760 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
16770 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
16780 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 75  allowed.  The au
16790 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
167a0 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
167b0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
167c0 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
167d0 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
167e0 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
167f0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
16800 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
16810 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
16820 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
16830 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
16840 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
16850 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
16860 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
16870 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
16880 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
16890 72 72 6f 72 2e 20 20 49 66 20 74 68 65 20 61 75  rror.  If the au
168a0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
168b0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
168c0 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
168d0 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
168e0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
168f0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
16900 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
16910 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
16920 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
16930 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
16940 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
16950 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
16960 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
16970 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
16980 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
16990 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
169a0 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
169b0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
169c0 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
169d0 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63 61 6c  k.  When the cal
169e0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
169f0 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
16a00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
16a10 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
16a20 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
16a30 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
16a40 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
16a50 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
16a60 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
16a70 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
16a80 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
16a90 65 64 2e 20 20 49 66 20 74 68 65 20 61 75 74 68  ed.  If the auth
16aa0 6f 72 69 7a 65 72 20 63 6f 64 65 20 69 73 20 5b  orizer code is [
16ab0 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
16ac0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
16ad0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
16ae0 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
16af0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
16b00 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
16b10 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
16b20 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
16b30 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
16b40 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
16b50 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
16b60 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
16b70 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
16b80 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
16b90 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
16ba0 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
16bb0 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
16bc0 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
16bd0 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
16be0 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
16bf0 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
16c00 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
16c10 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
16c20 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
16c30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
16c40 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
16c50 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
16c60 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
16c70 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
16c80 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
16c90 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  . The second par
16ca0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
16cb0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
16cc0 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f  integer [SQLITE_
16cd0 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
16ce0 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
16cf0 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63  es.** the partic
16d00 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62  ular action to b
16d10 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 54 68  e authorized. Th
16d20 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
16d30 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
16d40 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
16d50 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
16d60 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
16d70 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
16d80 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
16d90 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
16da0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
16db0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ized..**.** An a
16dc0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65  uthorizer is use
16dd0 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
16de0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
16df0 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ing].** SQL stat
16e00 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
16e10 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c  ntrusted source,
16e20 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
16e30 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
16e40 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79  ts.** do not try
16e50 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20   to access data 
16e60 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
16e70 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
16e80 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
16e90 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75  .** try to execu
16ea0 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
16eb0 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
16ec0 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
16ed0 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
16ee0 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
16ef0 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
16f00 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
16f10 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
16f20 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
16f30 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
16f40 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
16f50 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
16f60 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
16f70 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
16f80 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
16f90 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
16fa0 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
16fb0 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
16fc0 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
16fd0 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
16fe0 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
16ff0 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c  QL is being [sql
17000 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
17010 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a  repared] that.**
17020 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
17030 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45  thing except [SE
17040 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73  LECT] statements
17050 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
17060 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74  ions that need t
17070 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72  o process SQL fr
17080 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  om untrusted sou
17090 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c  rces.** might al
170a0 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65  so consider lowe
170b0 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69  ring resource li
170c0 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69  mits using [sqli
170d0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
170e0 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74  and limiting dat
170f0 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67  abase size using
17100 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63   the [max_page_c
17110 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a  ount] [PRAGMA].*
17120 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  * in addition to
17130 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72   using an author
17140 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c 79  izer..**.** Only
17150 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
17160 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
17170 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
17180 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
17190 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
171a0 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
171b0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
171c0 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
171d0 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
171e0 20 20 44 69 73 61 62 6c 65 20 74 68 65 20 61 75    Disable the au
171f0 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
17200 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
17210 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
17220 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
17230 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
17240 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
17250 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
17260 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
17270 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
17280 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
17290 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
172a0 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
172b0 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
172c0 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
172d0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
172e0 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
172f0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
17300 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
17310 2a 0a 2a 2a 20 7b 48 31 32 35 30 31 7d 20 54 68  *.** {H12501} Th
17320 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
17330 75 74 68 6f 72 69 7a 65 72 28 44 2c 2e 2e 2e 29  uthorizer(D,...)
17340 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
17350 73 74 65 72 73 20 61 0a 2a 2a 20 20 20 20 20 20  sters a.**      
17360 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72 20 63      authorizer c
17370 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 64 61 74  allback with dat
17380 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17390 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30   D..**.** {H1250
173a0 32 7d 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  2} The authorize
173b0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
173c0 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61  voked as SQL sta
173d0 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 20  tements are.**  
173e0 20 20 20 20 20 20 20 20 62 65 69 6e 67 20 63 6f          being co
173f0 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  mpiled..**.** {H
17400 31 32 35 30 33 7d 20 49 66 20 74 68 65 20 61 75  12503} If the au
17410 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17420 6b 20 72 65 74 75 72 6e 73 20 61 6e 79 20 76 61  k returns any va
17430 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a  lue other than.*
17440 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
17450 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
17460 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
17470 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 6e 0a  ITE_DENY], then.
17480 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
17490 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
174a0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
174b0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 63  lent call that c
174c0 61 75 73 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  aused.**        
174d0 20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72    the authorizer
174e0 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e   callback to run
174f0 20 73 68 61 6c 6c 20 66 61 69 6c 20 77 69 74 68   shall fail with
17500 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   an.**          
17510 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65  [SQLITE_ERROR] e
17520 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e  rror code and an
17530 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72   appropriate err
17540 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
17550 2a 20 7b 48 31 32 35 30 34 7d 20 57 68 65 6e 20  * {H12504} When 
17560 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
17570 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
17580 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
17590 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 20 20   operation.**   
175a0 20 20 20 20 20 20 20 64 65 73 63 72 69 62 65 64         described
175b0 20 69 73 20 70 72 6f 63 65 73 73 65 64 20 6e 6f   is processed no
175c0 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  rmally..**.** {H
175d0 31 32 35 30 35 7d 20 57 68 65 6e 20 74 68 65 20  12505} When the 
175e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
175f0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
17600 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
17610 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
17620 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
17630 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
17640 63 61 6c 6c 20 74 68 61 74 20 63 61 75 73 65 64  call that caused
17650 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
17660 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17670 62 61 63 6b 20 74 6f 20 72 75 6e 20 73 68 61 6c  back to run shal
17680 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20 20 20 20  l fail.**       
17690 20 20 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49     with an [SQLI
176a0 54 45 5f 45 52 52 4f 52 5d 20 65 72 72 6f 72 20  TE_ERROR] error 
176b0 63 6f 64 65 20 61 6e 64 20 61 6e 20 65 72 72 6f  code and an erro
176c0 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20 20 20  r message.**    
176d0 20 20 20 20 20 20 65 78 70 6c 61 69 6e 69 6e 67        explaining
176e0 20 74 68 61 74 20 61 63 63 65 73 73 20 69 73 20   that access is 
176f0 64 65 6e 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  denied..**.** {H
17700 31 32 35 30 36 7d 20 49 66 20 74 68 65 20 61 75  12506} If the au
17710 74 68 6f 72 69 7a 65 72 20 63 6f 64 65 20 28 74  thorizer code (t
17720 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
17730 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
17740 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  er.**          c
17750 61 6c 6c 62 61 63 6b 29 20 69 73 20 5b 53 51 4c  allback) is [SQL
17760 49 54 45 5f 52 45 41 44 5d 20 61 6e 64 20 74 68  ITE_READ] and th
17770 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
17780 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
17790 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
177a0 45 5f 49 47 4e 4f 52 45 5d 2c 20 74 68 65 6e 20  E_IGNORE], then 
177b0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
177c0 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
177d0 75 63 74 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  ucted to.**     
177e0 20 20 20 20 20 69 6e 73 65 72 74 20 61 20 4e 55       insert a NU
177f0 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
17800 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
17810 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
17820 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20   have.**        
17830 20 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b    been read if [
17840 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
17850 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  een returned..**
17860 0a 2a 2a 20 7b 48 31 32 35 30 37 7d 20 49 66 20  .** {H12507} If 
17870 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
17880 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72  ode (the 2nd par
17890 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
178a0 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20  thorizer.**     
178b0 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69       callback) i
178c0 73 20 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72  s anything other
178d0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 45   than [SQLITE_RE
178e0 41 44 5d 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  AD], then.**    
178f0 20 20 20 20 20 20 61 20 72 65 74 75 72 6e 20 6f        a return o
17900 66 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  f [SQLITE_IGNORE
17910 5d 20 68 61 73 20 74 68 65 20 73 61 6d 65 20 65  ] has the same e
17920 66 66 65 63 74 20 61 73 20 5b 53 51 4c 49 54 45  ffect as [SQLITE
17930 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  _DENY]..**.** {H
17940 31 32 35 31 30 7d 20 54 68 65 20 66 69 72 73 74  12510} The first
17950 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
17960 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
17970 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
17980 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  of.**          t
17990 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
179a0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
179b0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
179c0 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  r()] interface..
179d0 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 31 7d 20 54  **.** {H12511} T
179e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
179f0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
17a00 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
17a10 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  r.**          [S
17a20 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
17a30 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
17a40 70 65 63 69 66 69 65 73 20 74 68 65 20 70 61 72  pecifies the par
17a50 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 0a 2a  ticular action.*
17a60 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 62 65  *          to be
17a70 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
17a80 2a 2a 20 7b 48 31 32 35 31 32 7d 20 54 68 65 20  ** {H12512} The 
17a90 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
17aa0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  xth parameters t
17ab0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
17ac0 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  re.**          z
17ad0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
17ae0 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
17af0 61 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ain.**          
17b00 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69  additional detai
17b10 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
17b20 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
17b30 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ized..**.** {H12
17b40 35 32 30 7d 20 45 61 63 68 20 63 61 6c 6c 20 74  520} Each call t
17b50 6f 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  o [sqlite3_set_a
17b60 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 6f 76 65  uthorizer()] ove
17b70 72 72 69 64 65 73 0a 2a 2a 20 20 20 20 20 20 20  rrides.**       
17b80 20 20 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c     any previousl
17b90 79 20 69 6e 73 74 61 6c 6c 65 64 20 61 75 74 68  y installed auth
17ba0 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  orizer..**.** {H
17bb0 31 32 35 32 31 7d 20 41 20 4e 55 4c 4c 20 61 75  12521} A NULL au
17bc0 74 68 6f 72 69 7a 65 72 20 6d 65 61 6e 73 20 74  thorizer means t
17bd0 68 61 74 20 6e 6f 20 61 75 74 68 6f 72 69 7a 61  hat no authoriza
17be0 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
17bf0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
17c00 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  oked..**.** {H12
17c10 35 32 32 7d 20 54 68 65 20 64 65 66 61 75 6c 74  522} The default
17c20 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 4e   authorizer is N
17c30 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
17c40 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
17c50 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
17c60 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
17c70 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
17c80 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
17c90 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
17ca0 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
17cb0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
17cc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17cd0 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
17ce0 72 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 39 30  rn Codes {H12590
17cf0 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a  } <H12500>.**.**
17d00 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
17d10 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
17d20 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
17d30 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
17d40 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
17d50 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
17d60 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
17d70 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
17d80 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
17d90 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
17da0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
17db0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
17dc0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
17dd0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
17de0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
17df0 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
17e00 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
17e10 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
17e20 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
17e30 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
17e40 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
17e50 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
17e60 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
17e70 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
17e80 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
17e90 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
17ea0 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
17eb0 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
17ec0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
17ed0 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
17ee0 65 73 20 7b 48 31 32 35 35 30 7d 20 3c 48 31 32  es {H12550} <H12
17ef0 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  500>.**.** The [
17f00 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
17f10 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
17f20 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
17f30 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
17f40 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
17f50 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
17f60 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
17f70 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
17f80 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
17f90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
17fa0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
17fb0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
17fc0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
17fd0 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
17fe0 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
17ff0 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
18000 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
18010 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
18020 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18030 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
18040 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
18050 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
18060 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
18070 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
18080 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
18090 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
180a0 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
180b0 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
180c0 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
180d0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
180e0 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
180f0 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
18100 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
18110 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
18120 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
18130 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
18140 20 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   The 5th paramet
18150 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
18160 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18170 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
18180 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
18190 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
181a0 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
181b0 61 62 6c 65 2e 20 20 54 68 65 20 36 74 68 20 70  able.  The 6th p
181c0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
181d0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
181e0 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
181f0 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
18200 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
18210 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
18220 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
18230 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
18240 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
18250 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
18260 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
18270 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
18280 53 51 4c 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20  SQL code..**.** 
18290 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
182a0 2a 20 7b 48 31 32 35 35 31 7d 20 54 68 65 20 73  * {H12551} The s
182b0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
182c0 74 6f 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  to an.**        
182d0 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61    [sqlite3_set_a
182e0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
182f0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d  orizer callback]
18300 20 69 73 20 61 6c 77 61 79 73 20 61 6e 20 69 6e   is always an in
18310 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  teger.**        
18320 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c    [SQLITE_COPY |
18330 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64 65   authorizer code
18340 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
18350 20 77 68 61 74 20 61 63 74 69 6f 6e 0a 2a 2a 20   what action.** 
18360 20 20 20 20 20 20 20 20 20 69 73 20 62 65 69 6e           is bein
18370 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  g authorized..**
18380 0a 2a 2a 20 7b 48 31 32 35 35 32 7d 20 54 68 65  .** {H12552} The
18390 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72   3rd and 4th par
183a0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 0a 2a  ameters to the.*
183b0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
183c0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
183d0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 61 74 69  er | authorizati
183e0 6f 6e 20 63 61 6c 6c 62 61 63 6b 5d 0a 2a 2a 20  on callback].** 
183f0 20 20 20 20 20 20 20 20 20 77 69 6c 6c 20 62 65           will be
18400 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
18410 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
18420 20 77 68 69 63 68 0a 2a 2a 20 20 20 20 20 20 20   which.**       
18430 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20     [SQLITE_COPY 
18440 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64  | authorizer cod
18450 65 5d 20 69 73 20 75 73 65 64 20 61 73 20 74 68  e] is used as th
18460 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18470 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35  er..**.** {H1255
18480 33 7d 20 54 68 65 20 35 74 68 20 70 61 72 61 6d  3} The 5th param
18490 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20  eter to the.**  
184a0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
184b0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
184c0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
184d0 6c 62 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61  lback] is the na
184e0 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  me.**          o
184f0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
18500 65 78 61 6d 70 6c 65 3a 20 22 6d 61 69 6e 22 2c  example: "main",
18510 20 22 74 65 6d 70 22 2c 20 65 74 63 2e 29 20 69   "temp", etc.) i
18520 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 0a 2a 2a  f applicable..**
18530 0a 2a 2a 20 7b 48 31 32 35 35 34 7d 20 54 68 65  .** {H12554} The
18540 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
18550 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  o the.**        
18560 20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61    [sqlite3_set_a
18570 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
18580 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 5d  orizer callback]
18590 20 69 73 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20   is the name.** 
185a0 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65 20           of the 
185b0 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
185c0 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
185d0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
185e0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  or.**          t
185f0 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
18600 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
18610 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
18620 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
18630 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  m.**          to
18640 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
18650 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..*/./**********
18660 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18670 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18680 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 3rd **********
18690 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 4th *********
186a0 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  **/.#define SQLI
186b0 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20  TE_CREATE_INDEX 
186c0 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20           1   /* 
186d0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
186e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
186f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18700 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20  E_CREATE_TABLE  
18710 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54          2   /* T
18720 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
18730 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18740 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18750 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44  _CREATE_TEMP_IND
18760 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e  EX     3   /* In
18770 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
18780 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
18790 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
187a0 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c  CREATE_TEMP_TABL
187b0 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62  E     4   /* Tab
187c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
187d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
187e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
187f0 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47  REATE_TEMP_TRIGG
18800 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67  ER   5   /* Trig
18810 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
18820 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
18830 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
18840 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20  EATE_TEMP_VIEW  
18850 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20      6   /* View 
18860 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
18870 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18880 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
18890 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  ATE_TRIGGER     
188a0 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65     7   /* Trigge
188b0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
188c0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
188d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
188e0 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  TE_VIEW         
188f0 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    8   /* View Na
18900 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
18910 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18920 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54  ine SQLITE_DELET
18930 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
18940 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   9   /* Table Na
18950 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
18960 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18970 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49  ne SQLITE_DROP_I
18980 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31  NDEX           1
18990 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  0   /* Index Nam
189a0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
189b0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
189c0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41  e SQLITE_DROP_TA
189d0 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31  BLE           11
189e0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
189f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18a00 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18a10 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
18a20 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20  P_INDEX      12 
18a30 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
18a40 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
18a50 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18a60 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
18a70 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20  _TABLE      13  
18a80 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
18a90 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18aa0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18ab0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
18ac0 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20  TRIGGER    14   
18ad0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
18ae0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
18af0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18b00 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56  LITE_DROP_TEMP_V
18b10 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f  IEW       15   /
18b20 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
18b30 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18b40 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18b50 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52  ITE_DROP_TRIGGER
18b60 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a           16   /*
18b70 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
18b80 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18b90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18ba0 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20  TE_DROP_VIEW    
18bb0 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20          17   /* 
18bc0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
18bd0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
18be0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18bf0 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20  E_INSERT        
18c00 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54         18   /* T
18c10 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
18c20 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18c30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18c40 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
18c50 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72        19   /* Pr
18c60 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73  agma Name     1s
18c70 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f  t arg or NULL */
18c80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18c90 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
18ca0 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62       20   /* Tab
18cb0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
18cc0 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
18cd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
18ce0 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
18cf0 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c      21   /* NULL
18d00 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
18d10 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
18d20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
18d30 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20  ANSACTION       
18d40 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c 20     22   /* NULL 
18d50 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
18d60 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18d70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44  efine SQLITE_UPD
18d80 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
18d90 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    23   /* Table 
18da0 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
18db0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
18dc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41  fine SQLITE_ATTA
18dd0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
18de0 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d   24   /* Filenam
18df0 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  e        NULL   
18e00 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18e10 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43  ine SQLITE_DETAC
18e20 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
18e30 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  25   /* Database
18e40 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
18e50 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18e60 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f  ne SQLITE_ALTER_
18e70 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
18e80 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
18e90 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d  Name   Table Nam
18ea0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
18eb0 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58  e SQLITE_REINDEX
18ec0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37                27
18ed0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
18ee0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18ef0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18f00 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20   SQLITE_ANALYZE 
18f10 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20               28 
18f20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
18f30 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18f40 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18f50 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54  SQLITE_CREATE_VT
18f60 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20  ABLE        29  
18f70 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
18f80 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
18f90 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18fa0 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c  QLITE_DROP_VTABL
18fb0 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20  E          30   
18fc0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
18fd0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
18fe0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18ff0 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20  LITE_FUNCTION   
19000 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f            31   /
19010 2a 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20  * Function Name 
19020 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
19030 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19040 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
19050 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
19060 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
19070 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
19080 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
19090 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
190a0 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c 53 36  ons {H12280} <S6
190b0 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0400>.**.** Thes
190c0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
190d0 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
190e0 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
190f0 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
19100 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
19110 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
19120 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
19130 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ents..**.** The 
19140 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
19150 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
19160 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
19170 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
19180 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
19190 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
191a0 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
191b0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
191c0 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63 61  ep()]..** The ca
191d0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
191e0 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
191f0 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   of the SQL stat
19200 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61 73  ement text.** as
19210 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
19220 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
19230 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  uting.  Addition
19240 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63 63  al callbacks occ
19250 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
19260 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
19270 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
19280 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
19290 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
192a0 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
192b0 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
192c0 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
192d0 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  igger..**.** The
192e0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
192f0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
19300 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
19310 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
19320 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
19330 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
19340 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61    The profile ca
19350 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
19360 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
19370 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
19380 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
19390 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
193a0 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
193b0 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
193c0 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 0a  took to run..**.
193d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
193e0 72 6f 66 69 6c 65 28 29 20 41 50 49 20 69 73 20  rofile() API is 
193f0 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64  currently consid
19400 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ered experimenta
19410 6c 20 61 6e 64 0a 2a 2a 20 69 73 20 73 75 62 6a  l and.** is subj
19420 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f 72  ect to change or
19430 20 72 65 6d 6f 76 61 6c 20 69 6e 20 61 20 66 75   removal in a fu
19440 74 75 72 65 20 72 65 6c 65 61 73 65 2e 0a 2a 2a  ture release..**
19450 0a 2a 2a 20 54 68 65 20 74 72 69 67 67 65 72 20  .** The trigger 
19460 72 65 70 6f 72 74 69 6e 67 20 66 65 61 74 75 72  reporting featur
19470 65 20 6f 66 20 74 68 65 20 74 72 61 63 65 20 63  e of the trace c
19480 61 6c 6c 62 61 63 6b 20 69 73 20 63 6f 6e 73 69  allback is consi
19490 64 65 72 65 64 0a 2a 2a 20 65 78 70 65 72 69 6d  dered.** experim
194a0 65 6e 74 61 6c 20 61 6e 64 20 69 73 20 73 75 62  ental and is sub
194b0 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 6f  ject to change o
194c0 72 20 72 65 6d 6f 76 61 6c 20 69 6e 20 66 75 74  r removal in fut
194d0 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  ure releases..**
194e0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
194f0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
19500 20 61 6c 73 6f 20 61 64 64 20 6e 65 77 20 74 72   also add new tr
19510 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ace callback.** 
19520 69 6e 76 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 0a  invocations..**.
19530 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
19540 2a 0a 2a 2a 20 7b 48 31 32 32 38 31 7d 20 54 68  *.** {H12281} Th
19550 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
19560 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
19570 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  y [sqlite3_trace
19580 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ()] is.**       
19590 20 20 20 77 68 65 6e 65 76 65 72 20 61 6e 20 53     whenever an S
195a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  QL statement fir
195b0 73 74 20 62 65 67 69 6e 73 20 74 6f 20 65 78 65  st begins to exe
195c0 63 75 74 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20  cute and.**     
195d0 20 20 20 20 20 77 68 65 6e 65 76 65 72 20 61 20       whenever a 
195e0 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72  trigger subprogr
195f0 61 6d 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  am first begins 
19600 74 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48  to run..**.** {H
19610 31 32 32 38 32 7d 20 45 61 63 68 20 63 61 6c 6c  12282} Each call
19620 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
19630 63 65 28 29 5d 20 6f 76 65 72 72 69 64 65 73 20  ce()] overrides 
19640 74 68 65 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a  the previously.*
19650 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73  *          regis
19660 74 65 72 65 64 20 74 72 61 63 65 20 63 61 6c 6c  tered trace call
19670 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  back..**.** {H12
19680 32 38 33 7d 20 41 20 4e 55 4c 4c 20 74 72 61 63  283} A NULL trac
19690 65 20 63 61 6c 6c 62 61 63 6b 20 64 69 73 61 62  e callback disab
196a0 6c 65 73 20 74 72 61 63 69 6e 67 2e 0a 2a 2a 0a  les tracing..**.
196b0 2a 2a 20 7b 48 31 32 32 38 34 7d 20 54 68 65 20  ** {H12284} The 
196c0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
196d0 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c  o the trace call
196e0 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
196f0 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
19700 65 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  e pointer which 
19710 77 61 73 20 74 68 65 20 33 72 64 20 61 72 67 75  was the 3rd argu
19720 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
19730 5f 74 72 61 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _trace()]..**.**
19740 20 7b 48 31 32 32 38 35 7d 20 54 68 65 20 73 65   {H12285} The se
19750 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
19760 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62   the trace callb
19770 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20  ack is a.**     
19780 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
19790 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
197a0 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
197b0 20 6f 72 69 67 69 6e 61 6c 20 74 65 78 74 0a 2a   original text.*
197c0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
197d0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
197e0 61 73 20 69 74 20 77 61 73 20 70 61 73 73 65 64  as it was passed
197f0 20 69 6e 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70   into [sqlite3_p
19800 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20  repare_v2()].** 
19810 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
19820 65 71 75 69 76 61 6c 65 6e 74 2c 20 6f 72 20 61  equivalent, or a
19830 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e  n SQL comment in
19840 64 69 63 61 74 69 6e 67 20 74 68 65 20 62 65 67  dicating the beg
19850 69 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  inning.**       
19860 20 20 20 6f 66 20 61 20 74 72 69 67 67 65 72 20     of a trigger 
19870 73 75 62 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  subprogram..**.*
19880 2a 20 7b 48 31 32 32 38 37 7d 20 54 68 65 20 63  * {H12287} The c
19890 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
198a0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 5b   registered by [
198b0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
198c0 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  )] is invoked.**
198d0 20 20 20 20 20 20 20 20 20 20 61 73 20 65 61 63            as eac
198e0 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
198f0 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20  finishes..**.** 
19900 7b 48 31 32 32 38 38 7d 20 54 68 65 20 66 69 72  {H12288} The fir
19910 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
19920 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  the profile call
19930 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
19940 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  f.**          th
19950 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
19960 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66  to [sqlite3_prof
19970 69 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ile()]..**.** {H
19980 31 32 32 38 39 7d 20 54 68 65 20 73 65 63 6f 6e  12289} The secon
19990 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
199a0 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
199b0 61 63 6b 20 69 73 20 61 0a 2a 2a 20 20 20 20 20  ack is a.**     
199c0 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
199d0 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
199e0 67 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  g that contains 
199f0 74 68 65 20 63 6f 6d 70 6c 65 74 65 20 74 65 78  the complete tex
19a00 74 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  t of.**         
19a10 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
19a20 6e 74 20 61 73 20 69 74 20 77 61 73 20 70 72 6f  nt as it was pro
19a30 63 65 73 73 65 64 20 62 79 20 5b 73 71 6c 69 74  cessed by [sqlit
19a40 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
19a50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
19a60 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 2e 0a  the equivalent..
19a70 2a 2a 0a 2a 2a 20 7b 48 31 32 32 39 30 7d 20 54  **.** {H12290} T
19a80 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
19a90 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c  er to the profil
19aa0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
19ab0 20 65 73 74 69 6d 61 74 65 0a 2a 2a 20 20 20 20   estimate.**    
19ac0 20 20 20 20 20 20 6f 66 20 74 68 65 20 6e 75 6d        of the num
19ad0 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  ber of nanosecon
19ae0 64 73 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  ds of wall-clock
19af0 20 74 69 6d 65 20 72 65 71 75 69 72 65 64 20 74   time required t
19b00 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 75  o.**          ru
19b10 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
19b20 65 6e 74 20 66 72 6f 6d 20 73 74 61 72 74 20 74  ent from start t
19b30 6f 20 66 69 6e 69 73 68 2e 0a 2a 2f 0a 76 6f 69  o finish..*/.voi
19b40 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
19b50 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
19b60 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
19b70 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
19b80 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  d*);.void *sqlit
19b90 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
19ba0 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
19bb0 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
19bc0 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
19bd0 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
19be0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
19bf0 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
19c00 73 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31  ss Callbacks {H1
19c10 32 39 31 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a  2910} <S60400>.*
19c20 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
19c30 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63  e configures a c
19c40 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
19c50 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65   - the.** progre
19c60 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68  ss callback - th
19c70 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65  at is invoked pe
19c80 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
19c90 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e  g long.** runnin
19ca0 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  g calls to [sqli
19cb0 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
19cc0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
19cd0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  d.** [sqlite3_ge
19ce0 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20  t_table()].  An 
19cf0 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
19d00 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
19d10 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
19d20 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
19d30 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
19d40 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72  .**.** If the pr
19d50 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
19d60 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
19d70 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  , the operation 
19d80 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
19d90 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
19da0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
19db0 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
19dc0 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
19dd0 6e 20 61 20 47 55 49 20 64 69 61 6c 6f 67 20 62  n a GUI dialog b
19de0 6f 78 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ox..**.** INVARI
19df0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
19e00 39 31 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63  911} The callbac
19e10 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
19e20 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
19e30 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
19e40 72 28 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r().**          
19e50 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  is invoked perio
19e60 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
19e70 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
19e80 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  s to.**         
19e90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19ea0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 32  ]..**.** {H12912
19eb0 7d 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 63  } The progress c
19ec0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
19ed0 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 76 65 72  ed once for ever
19ee0 79 20 4e 20 76 69 72 74 75 61 6c 0a 2a 2a 20 20  y N virtual.**  
19ef0 20 20 20 20 20 20 20 20 6d 61 63 68 69 6e 65 20          machine 
19f00 6f 70 63 6f 64 65 73 2c 20 77 68 65 72 65 20 4e  opcodes, where N
19f10 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   is the second a
19f20 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20  rgument to.**   
19f30 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69         the [sqli
19f40 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
19f50 64 6c 65 72 28 29 5d 20 63 61 6c 6c 20 74 68 61  dler()] call tha
19f60 74 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20  t registered.** 
19f70 20 20 20 20 20 20 20 20 20 74 68 65 20 63 61 6c           the cal
19f80 6c 62 61 63 6b 2e 20 20 49 66 20 4e 20 69 73 20  lback.  If N is 
19f90 6c 65 73 73 20 74 68 61 6e 20 31 2c 20 73 71 6c  less than 1, sql
19fa0 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
19fb0 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 20  ndler().**      
19fc0 20 20 20 20 61 63 74 73 20 61 73 20 69 66 20 61      acts as if a
19fd0 20 4e 55 4c 4c 20 70 72 6f 67 72 65 73 73 20 68   NULL progress h
19fe0 61 6e 64 6c 65 72 20 68 61 64 20 62 65 65 6e 20  andler had been 
19ff0 73 70 65 63 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a  specified..**.**
1a000 20 7b 48 31 32 39 31 33 7d 20 54 68 65 20 70 72   {H12913} The pr
1a010 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
1a020 69 74 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69  itself is identi
1a030 66 69 65 64 20 62 79 20 74 68 65 20 74 68 69 72  fied by the thir
1a040 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  d.**          ar
1a050 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1a060 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1a070 65 72 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  er()..**.** {H12
1a080 39 31 34 7d 20 54 68 65 20 66 6f 75 72 74 68 20  914} The fourth 
1a090 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1a0a0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
1a0b0 64 6c 65 72 28 29 20 69 73 20 61 0a 2a 2a 20 20  dler() is a.**  
1a0c0 20 20 20 20 20 20 20 20 76 6f 69 64 20 70 6f 69          void poi
1a0d0 6e 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74  nter passed to t
1a0e0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
1a0f0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
1a100 20 66 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74   function each t
1a110 69 6d 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  ime it is invoke
1a120 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 35  d..**.** {H12915
1a130 7d 20 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b  } If a call to [
1a140 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1a150 72 65 73 75 6c 74 73 20 69 6e 20 66 65 77 65 72  results in fewer
1a160 20 74 68 61 6e 20 4e 20 6f 70 63 6f 64 65 73 0a   than N opcodes.
1a170 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 69 6e  **          bein
1a180 67 20 65 78 65 63 75 74 65 64 2c 20 74 68 65 6e  g executed, then
1a190 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
1a1a0 6c 6c 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20  llback is never 
1a1b0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  invoked..**.** {
1a1c0 48 31 32 39 31 36 7d 20 45 76 65 72 79 20 63 61  H12916} Every ca
1a1d0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ll to [sqlite3_p
1a1e0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1a1f0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
1a200 76 65 72 77 72 69 74 65 73 20 61 6e 79 20 70 72  verwrites any pr
1a210 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
1a220 72 65 64 20 70 72 6f 67 72 65 73 73 20 68 61 6e  red progress han
1a230 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  dler..**.** {H12
1a240 39 31 37 7d 20 49 66 20 74 68 65 20 70 72 6f 67  917} If the prog
1a250 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
1a260 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 20 74 68  lback is NULL th
1a270 65 6e 20 6e 6f 20 70 72 6f 67 72 65 73 73 0a 2a  en no progress.*
1a280 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e 64 6c  *          handl
1a290 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  er is invoked..*
1a2a0 2a 0a 2a 2a 20 7b 48 31 32 39 31 38 7d 20 49 66  *.** {H12918} If
1a2b0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
1a2c0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61  llback returns a
1a2d0 20 72 65 73 75 6c 74 20 6f 74 68 65 72 20 74 68   result other th
1a2e0 61 6e 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  an 0, then.**   
1a2f0 20 20 20 20 20 20 20 74 68 65 20 62 65 68 61 76         the behav
1a300 69 6f 72 20 69 73 20 61 20 69 66 20 5b 73 71 6c  ior is a if [sql
1a310 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1a320 5d 20 68 61 64 20 62 65 65 6e 20 63 61 6c 6c 65  ] had been calle
1a330 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c  d..**          <
1a340 53 33 30 35 30 30 3e 0a 2a 2f 0a 76 6f 69 64 20  S30500>.*/.void 
1a350 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1a360 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
1a370 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
1a380 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
1a390 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a3a0 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
1a3b0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
1a3c0 6e 20 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32  n {H12700} <S402
1a3d0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
1a3e0 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
1a3f0 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
1a400 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65   file whose name
1a410 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65   is given by the
1a420 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
1a430 75 6d 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e  ument. The filen
1a440 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
1a450 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
1a460 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
1a470 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
1a480 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1a490 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
1a4a0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
1a4b0 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
1a4c0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
1a4d0 20 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   A [database con
1a4e0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
1a4f0 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
1a500 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
1a510 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
1a520 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
1a530 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
1a540 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
1a550 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
1a560 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
1a570 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
1a580 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
1a590 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
1a5a0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
1a5b0 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
1a5c0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
1a5d0 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
1a5e0 63 74 2e 20 49 66 20 74 68 65 20 64 61 74 61 62  ct. If the datab
1a5f0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61  ase is opened (a
1a600 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73  nd/or created) s
1a610 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65  uccessfully, the
1a620 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  n.** [SQLITE_OK]
1a630 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
1a640 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
1a650 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
1a660 72 6e 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  rned.  The.** [s
1a670 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1a680 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
1a690 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  msg16()] routine
1a6a0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  s can be used to
1a6b0 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e   obtain.** an En
1a6c0 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64  glish language d
1a6d0 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68  escription of th
1a6e0 65 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  e error..**.** T
1a6f0 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
1a700 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61  ing for the data
1a710 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46  base will be UTF
1a720 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33  -8 if.** sqlite3
1a730 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
1a740 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1a750 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54  called and.** UT
1a760 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
1a770 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66  ve byte order if
1a780 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
1a790 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  ) is used..**.**
1a7a0 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
1a7b0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
1a7c0 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
1a7d0 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20  d, resources.** 
1a7e0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1a7f0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
1a800 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
1a810 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
1a820 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e  sed by.** passin
1a830 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
1a840 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
1a850 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
1a860 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
1a870 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  he sqlite3_open_
1a880 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
1a890 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
1a8a0 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65  3_open().** exce
1a8b0 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
1a8c0 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
1a8d0 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
1a8e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
1a8f0 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
1a900 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
1a910 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c  nection.  The fl
1a920 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 63 61  ags parameter ca
1a930 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
1a940 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
1a950 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
1a960 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
1a970 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
1a980 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1a990 45 58 5d 20 66 6c 61 67 3a 0a 2a 2a 0a 2a 2a 20  EX] flag:.**.** 
1a9a0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c  <dl>.** <dt>[SQL
1a9b0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
1a9c0 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
1a9d0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1a9e0 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
1a9f0 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
1aa00 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
1aa10 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
1aa20 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
1aa30 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a   returned.</dd>.
1aa40 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54  **.** <dt>[SQLIT
1aa50 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
1aa60 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1aa70 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1aa80 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
1aa90 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
1aaa0 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
1aab0 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
1aac0 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
1aad0 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
1aae0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
1aaf0 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
1ab00 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
1ab10 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
1ab20 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
1ab30 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
1ab40 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  eturned.</dd>.**
1ab50 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  .** <dt>[SQLITE_
1ab60 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
1ab70 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
1ab80 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
1ab90 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1aba0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1abb0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1abc0 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
1abd0 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f  s it if.** it do
1abe0 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
1abf0 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68  xist. This is th
1ac00 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  e behavior that 
1ac10 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
1ac20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
1ac30 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
1ac40 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a  _open16().</dd>.
1ac50 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </dl>.**.** I
1ac60 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
1ac70 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
1ac80 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  pen_v2() is not 
1ac90 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  one of the.** co
1aca0 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
1acb0 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66   above or one of
1acc0 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e   the combination
1acd0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f  s shown above co
1ace0 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74  mbined.** with t
1acf0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1ad00 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 2c 20 74  NOMUTEX] flag, t
1ad10 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1ad20 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
1ad30 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51 4c  *.** If the [SQL
1ad40 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
1ad50 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
1ad60 68 65 6e 20 6d 75 74 65 78 65 73 20 6f 6e 20 74  hen mutexes on t
1ad70 68 65 0a 2a 2a 20 6f 70 65 6e 65 64 20 5b 64 61  he.** opened [da
1ad80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ad90 6e 5d 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  n] are disabled 
1ada0 61 6e 64 20 74 68 65 20 61 70 70 6c 69 61 74 69  and the appliati
1adb0 6f 6e 20 6d 75 73 74 0a 2a 2a 20 69 6e 73 75 72  on must.** insur
1adc0 65 20 74 68 61 74 20 61 63 63 65 73 73 20 74 6f  e that access to
1add0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1ade0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 69  onnection] and i
1adf0 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ts associated.**
1ae00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1ae10 6d 65 6e 74 73 5d 20 69 73 20 73 65 72 69 61 6c  ments] is serial
1ae20 69 7a 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  ized.  The [SQLI
1ae30 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1ae40 20 66 6c 61 67 0a 2a 2a 20 69 73 20 74 68 65 20   flag.** is the 
1ae50 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
1ae60 20 69 73 20 53 51 4c 69 74 65 20 69 73 20 63 6f   is SQLite is co
1ae70 6e 66 69 67 75 72 65 64 20 75 73 69 6e 67 20 74  nfigured using t
1ae80 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
1ae90 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
1aea0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
1aeb0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
1aec0 5d 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  ] options.** to 
1aed0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
1aee0 29 5d 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  )].  The [SQLITE
1aef0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
1af00 6c 61 67 20 6f 6e 6c 79 20 6d 61 6b 65 73 20 61  lag only makes a
1af10 0a 2a 2a 20 64 69 66 66 65 72 65 6e 63 65 20 77  .** difference w
1af20 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e  hen SQLite is in
1af30 20 69 74 73 20 64 65 66 61 75 6c 74 20 5b 53 51   its default [SQ
1af40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
1af50 41 4c 49 5a 45 44 5d 20 6d 6f 64 65 2e 0a 2a 2a  ALIZED] mode..**
1af60 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65 6e  .** If the filen
1af70 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
1af80 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
1af90 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
1afa0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
1afb0 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
1afc0 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
1afd0 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72  .  This in-memor
1afe0 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
1aff0 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
1b000 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1b010 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
1b020 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1b030 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
1b040 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
1b050 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
1b060 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
1b070 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
1b080 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
1b090 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
1b0a0 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
1b0b0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
1b0c0 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
1b0d0 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
1b0e0 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
1b0f0 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
1b100 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
1b110 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
1b120 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
1b130 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
1b140 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ty..**.** If the
1b150 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
1b160 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
1b170 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
1b180 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
1b190 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
1b1a0 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 54 68   be created.  Th
1b1b0 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
1b1c0 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
1b1d0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
1b1e0 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
1b1f0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1b200 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
1b210 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75  d..**.** The fou
1b220 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
1b230 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1b240 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
1b250 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
1b260 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
1b270 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
1b280 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
1b290 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
1b2a0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
1b2b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
1b2c0 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20 74 68  ould use.  If th
1b2d0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1b2e0 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
1b2f0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
1b300 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1b310 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
1b320 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e   used..**.** <b>
1b330 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
1b340 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
1b350 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
1b360 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
1b370 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71  rgument.** of sq
1b380 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1b390 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1b3a0 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  () must be UTF-8
1b3b0 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
1b3c0 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
1b3d0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
1b3e0 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
1b3f0 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
1b400 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
1b410 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
1b420 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
1b430 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
1b440 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  hem into.** sqli
1b450 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
1b460 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
1b470 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
1b480 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 31  S:.**.** {H12701
1b490 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  } The [sqlite3_o
1b4a0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
1b4b0 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a  _open16()], and.
1b4c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1b4d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
1b4e0 69 6e 74 65 72 66 61 63 65 73 20 63 72 65 61 74  interfaces creat
1b4f0 65 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20  e a new.**      
1b500 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
1b510 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63 69  nnection] associ
1b520 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20 20 20  ated with.**    
1b530 20 20 20 20 20 20 74 68 65 20 64 61 74 61 62 61        the databa
1b540 73 65 20 66 69 6c 65 20 67 69 76 65 6e 20 69 6e  se file given in
1b550 20 74 68 65 69 72 20 66 69 72 73 74 20 70 61 72   their first par
1b560 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ameter..**.** {H
1b570 31 32 37 30 32 7d 20 54 68 65 20 66 69 6c 65 6e  12702} The filen
1b580 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
1b590 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
1b5a0 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20  TF-8.**         
1b5b0 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70   for [sqlite3_op
1b5c0 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  en()] and [sqlit
1b5d0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61 6e  e3_open_v2()] an
1b5e0 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20 20  d as UTF-16.**  
1b5f0 20 20 20 20 20 20 20 20 69 6e 20 74 68 65 20 6e          in the n
1b600 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1b610 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70   for [sqlite3_op
1b620 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  en16()]..**.** {
1b630 48 31 32 37 30 33 7d 20 41 20 73 75 63 63 65 73  H12703} A succes
1b640 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
1b650 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  of [sqlite3_open
1b660 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1b670 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  en16()],.**     
1b680 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
1b690 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 72 69 74  _open_v2()] writ
1b6a0 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  es a pointer to 
1b6b0 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20  a new.**        
1b6c0 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e    [database conn
1b6d0 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a 70 70  ection] into *pp
1b6e0 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30  Db..**.** {H1270
1b6f0 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
1b700 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
1b710 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
1b720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1b730 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1b740 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75   interfaces retu
1b750 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 75  rn [SQLITE_OK] u
1b760 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a 2a 2a 20  pon success,.** 
1b770 20 20 20 20 20 20 20 20 20 6f 72 20 61 6e 20 61           or an a
1b780 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
1b790 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75  r code] on failu
1b7a0 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30  re..**.** {H1270
1b7b0 36 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 74  6} The default t
1b7c0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ext encoding for
1b7d0 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65 20   a new database 
1b7e0 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
1b7f0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1b800 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b 73  e3_open()] or [s
1b810 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1b820 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 2e  ] will be UTF-8.
1b830 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 37 7d 20  .**.** {H12707} 
1b840 54 68 65 20 64 65 66 61 75 6c 74 20 74 65 78 74  The default text
1b850 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61 20   encoding for a 
1b860 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 72 65  new database cre
1b870 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ated using.**   
1b880 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1b890 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c 6c 20 62  open16()] will b
1b8a0 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
1b8b0 7b 48 31 32 37 30 39 7d 20 54 68 65 20 5b 73 71  {H12709} The [sq
1b8c0 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c 44 29 5d  lite3_open(F,D)]
1b8d0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 71   interface is eq
1b8e0 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a 20 20  uivalent to.**  
1b8f0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1b900 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 30  _open_v2(F,D,G,0
1b910 29 5d 20 77 68 65 72 65 20 74 68 65 20 47 20 70  )] where the G p
1b920 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20  arameter is.**  
1b930 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
1b940 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 7c  OPEN_READWRITE]|
1b950 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
1b960 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ATE]..**.** {H12
1b970 37 31 31 7d 20 49 66 20 74 68 65 20 47 20 70 61  711} If the G pa
1b980 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
1b990 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c  te3_open_v2(F,D,
1b9a0 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20 74  G,V)] contains t
1b9b0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  he.**          b
1b9c0 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  it value [SQLITE
1b9d0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
1b9e0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
1b9f0 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20 20  e is opened.**  
1ba00 20 20 20 20 20 20 20 20 66 6f 72 20 72 65 61 64          for read
1ba10 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ing only..**.** 
1ba20 7b 48 31 32 37 31 32 7d 20 49 66 20 74 68 65 20  {H12712} If the 
1ba30 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  G parameter to [
1ba40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1ba50 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69  F,D,G,V)] contai
1ba60 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
1ba70 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51     bit value [SQ
1ba80 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1ba90 49 54 45 5d 20 74 68 65 6e 20 74 68 65 20 64 61  ITE] then the da
1baa0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1bab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 61  .**          rea
1bac0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
1bad0 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
1bae0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c   for reading onl
1baf0 79 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  y if the.**     
1bb00 20 20 20 20 20 66 69 6c 65 20 69 73 20 77 72 69       file is wri
1bb10 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
1bb20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
1bb30 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  stem..**.** {H12
1bb40 37 31 33 7d 20 49 66 20 74 68 65 20 47 20 70 61  713} If the G pa
1bb50 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
1bb60 74 65 33 5f 6f 70 65 6e 28 76 32 28 46 2c 44 2c  te3_open(v2(F,D,
1bb70 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74 68 65 0a  G,V)] omits the.
1bb80 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74 20  **          bit 
1bb90 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50  value [SQLITE_OP
1bba0 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20 74  EN_CREATE] and t
1bbb0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
1bbc0 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20   not.**         
1bbd0 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69 73   previously exis
1bbe0 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
1bbf0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  eturned..**.** {
1bc00 48 31 32 37 31 34 7d 20 49 66 20 74 68 65 20 47  H12714} If the G
1bc10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
1bc20 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76 32 28 46  qlite3_open(v2(F
1bc30 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e  ,D,G,V)] contain
1bc40 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
1bc50 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c    bit value [SQL
1bc60 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
1bc70 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
1bc80 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20  e does not.**   
1bc90 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c         previousl
1bca0 79 20 65 78 69 73 74 2c 20 74 68 65 6e 20 61 6e  y exist, then an
1bcb0 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
1bcc0 20 74 6f 20 63 72 65 61 74 65 20 61 6e 64 0a 2a   to create and.*
1bcd0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 69 74 69  *          initi
1bce0 61 6c 69 7a 65 20 74 68 65 20 64 61 74 61 62 61  alize the databa
1bcf0 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31  se..**.** {H1271
1bd00 37 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61  7} If the filena
1bd10 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  me argument to [
1bd20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
1bd30 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
1bd40 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
1bd50 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
1bd60 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a 6d 65 6d  n_v2()] is ":mem
1bd70 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20 70  ory:", then an p
1bd80 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20 20  rivate,.**      
1bd90 20 20 20 20 65 70 68 65 6d 65 72 61 6c 2c 20 69      ephemeral, i
1bda0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1bdb0 65 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  e is created for
1bdc0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
1bdd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74 6f  .**          <to
1bde0 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50 45  do>Is SQLITE_OPE
1bdf0 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45 5f  N_CREATE|SQLITE_
1be00 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 72  OPEN_READWRITE r
1be10 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20 20  equired.**      
1be20 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f      in sqlite3_o
1be30 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f 3e  pen_v2()?</todo>
1be40 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 39 7d 20  .**.** {H12719} 
1be50 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1be60 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d  is NULL or an em
1be70 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
1be80 20 61 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20   a private,.**  
1be90 20 20 20 20 20 20 20 20 65 70 68 65 6d 65 72 61          ephemera
1bea0 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61  l on-disk databa
1beb0 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74  se will be creat
1bec0 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ed..**          
1bed0 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f  <todo>Is SQLITE_
1bee0 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49  OPEN_CREATE|SQLI
1bef0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1bf00 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20  E required.**   
1bf10 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65         in sqlite
1bf20 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f  3_open_v2()?</to
1bf30 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 32  do>.**.** {H1272
1bf40 31 7d 20 54 68 65 20 5b 64 61 74 61 62 61 73 65  1} The [database
1bf50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 72 65   connection] cre
1bf60 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ated by [sqlite3
1bf70 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56  _open_v2(F,D,G,V
1bf80 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  )].**          w
1bf90 69 6c 6c 20 75 73 65 20 74 68 65 20 5b 73 71 6c  ill use the [sql
1bfa0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1bfb0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
1bfc0 68 65 20 56 20 70 61 72 61 6d 65 74 65 72 2c 0a  he V parameter,.
1bfd0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74  **          or t
1bfe0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1bff0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1c000 69 66 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70  if V is a NULL p
1c010 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ointer..**.** {H
1c020 31 32 37 32 33 7d 20 54 77 6f 20 5b 64 61 74 61  12723} Two [data
1c030 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1c040 5d 20 77 69 6c 6c 20 73 68 61 72 65 20 61 20 63  ] will share a c
1c050 6f 6d 6d 6f 6e 20 63 61 63 68 65 20 69 66 20 62  ommon cache if b
1c060 6f 74 68 20 77 65 72 65 0a 2a 2a 20 20 20 20 20  oth were.**     
1c070 20 20 20 20 20 6f 70 65 6e 65 64 20 77 69 74 68       opened with
1c080 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 77 68   the same VFS wh
1c090 69 6c 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  ile [shared cach
1c0a0 65 20 6d 6f 64 65 5d 20 77 61 73 20 65 6e 61 62  e mode] was enab
1c0b0 6c 65 64 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  led and.**      
1c0c0 20 20 20 20 69 66 20 62 6f 74 68 20 66 69 6c 65      if both file
1c0d0 6e 61 6d 65 73 20 63 6f 6d 70 61 72 65 20 65 71  names compare eq
1c0e0 75 61 6c 20 75 73 69 6e 67 20 6d 65 6d 63 6d 70  ual using memcmp
1c0f0 28 29 20 61 66 74 65 72 20 68 61 76 69 6e 67 20  () after having 
1c100 62 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  been.**         
1c110 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 74 68   processed by th
1c120 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  e [sqlite3_vfs |
1c130 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 5d 20   xFullPathname] 
1c140 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 56 46  method of the VF
1c150 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  S..*/.int sqlite
1c160 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
1c170 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1c180 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1c190 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1c1a0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1c1b0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
1c1c0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1c1d0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
1c1e0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
1c1f0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
1c200 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1c210 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1c220 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
1c230 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
1c240 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1c250 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1c260 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
1c270 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
1c280 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1c290 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1c2a0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1c2b0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1c2c0 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
1c2d0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1c2e0 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
1c2f0 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
1c300 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
1c310 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
1c320 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
1c330 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
1c340 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
1c350 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
1c360 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
1c370 61 67 65 73 20 7b 48 31 32 38 30 30 7d 20 3c 53  ages {H12800} <S
1c380 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  60200>.**.** The
1c390 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
1c3a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
1c3b0 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
1c3c0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
1c3d0 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
1c3e0 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20  esult code] for 
1c3f0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
1c400 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a  failed sqlite3_*
1c410 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73   API call.** ass
1c420 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b  ociated with a [
1c430 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c440 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72  ion]. If a prior
1c450 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64   API call failed
1c460 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74  .** but the most
1c470 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c   recent API call
1c480 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20   succeeded, the 
1c490 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
1c4a0 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72  m.** sqlite3_err
1c4b0 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69  code() is undefi
1c4c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
1c4d0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
1c4e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
1c4f0 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
1c500 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
1c510 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
1c520 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
1c530 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
1c540 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
1c550 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d 6f  ctively..** Memo
1c560 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
1c570 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
1c580 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
1c590 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
1c5a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
1c5b0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
1c5c0 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
1c5d0 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
1c5e0 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
1c5f0 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
1c600 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
1c610 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
1c620 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
1c630 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
1c640 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
1c650 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
1c660 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63  * If an interfac
1c670 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c  e fails with SQL
1c680 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74  ITE_MISUSE, that
1c690 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72   means the inter
1c6a0 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f  face.** was invo
1c6b0 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ked incorrectly 
1c6c0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
1c6d0 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73  on.  In that cas
1c6e0 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  e, the.** error 
1c6f0 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
1c700 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20   may or may not 
1c710 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e  be set..**.** IN
1c720 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
1c730 7b 48 31 32 38 30 31 7d 20 54 68 65 20 5b 73 71  {H12801} The [sq
1c740 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29  lite3_errcode(D)
1c750 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
1c760 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 0a  rns the numeric.
1c770 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 72 65 73  **          [res
1c780 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78  ult code] or [ex
1c790 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
1c7a0 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74  de] for the most
1c7b0 20 72 65 63 65 6e 74 6c 79 0a 2a 2a 20 20 20 20   recently.**    
1c7c0 20 20 20 20 20 20 66 61 69 6c 65 64 20 69 6e 74        failed int
1c7d0 65 72 66 61 63 65 20 63 61 6c 6c 20 61 73 73 6f  erface call asso
1c7e0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1c7f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1c800 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  tion] D..**.** {
1c810 48 31 32 38 30 33 7d 20 54 68 65 20 5b 73 71 6c  H12803} The [sql
1c820 69 74 65 33 5f 65 72 72 6d 73 67 28 44 29 5d 20  ite3_errmsg(D)] 
1c830 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
1c840 6d 73 67 31 36 28 44 29 5d 0a 2a 2a 20 20 20 20  msg16(D)].**    
1c850 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
1c860 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
1c870 6c 61 6e 67 75 61 67 65 20 74 65 78 74 20 74 68  language text th
1c880 61 74 20 64 65 73 63 72 69 62 65 73 0a 2a 2a 20  at describes.** 
1c890 20 20 20 20 20 20 20 20 20 74 68 65 20 65 72 72           the err
1c8a0 6f 72 20 69 6e 20 74 68 65 20 6d 6f 73 74 6c 79  or in the mostly
1c8b0 20 72 65 63 65 6e 74 6c 79 20 66 61 69 6c 65 64   recently failed
1c8c0 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 2c   interface call,
1c8d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63  .**          enc
1c8e0 6f 64 65 64 20 61 73 20 65 69 74 68 65 72 20 55  oded as either U
1c8f0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
1c900 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
1c910 2a 2a 20 7b 48 31 32 38 30 37 7d 20 54 68 65 20  ** {H12807} The 
1c920 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
1c930 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   by [sqlite3_err
1c940 6d 73 67 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  msg()] and [sqli
1c950 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a  te3_errmsg16()].
1c960 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65 20  **          are 
1c970 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
1c980 6e 65 78 74 20 53 51 4c 69 74 65 20 69 6e 74 65  next SQLite inte
1c990 72 66 61 63 65 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  rface call..**.*
1c9a0 2a 20 7b 48 31 32 38 30 38 7d 20 43 61 6c 6c 73  * {H12808} Calls
1c9b0 20 74 6f 20 41 50 49 20 72 6f 75 74 69 6e 65 73   to API routines
1c9c0 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 72 65 74   that do not ret
1c9d0 75 72 6e 20 61 6e 20 65 72 72 6f 72 20 63 6f 64  urn an error cod
1c9e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 28 65  e.**          (e
1c9f0 78 61 6d 70 6c 65 3a 20 5b 73 71 6c 69 74 65 33  xample: [sqlite3
1ca00 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 29 20  _data_count()]) 
1ca10 64 6f 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20  do not.**       
1ca20 20 20 20 63 68 61 6e 67 65 20 74 68 65 20 65 72     change the er
1ca30 72 6f 72 20 63 6f 64 65 20 6f 72 20 6d 65 73 73  ror code or mess
1ca40 61 67 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a  age returned by.
1ca50 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1ca60 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 2c  ite3_errcode()],
1ca70 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1ca80 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
1ca90 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a  _errmsg16()]..**
1caa0 0a 2a 2a 20 7b 48 31 32 38 30 39 7d 20 49 6e 74  .** {H12809} Int
1cab0 65 72 66 61 63 65 73 20 74 68 61 74 20 61 72 65  erfaces that are
1cac0 20 6e 6f 74 20 61 73 73 6f 63 69 61 74 65 64 20   not associated 
1cad0 77 69 74 68 20 61 20 73 70 65 63 69 66 69 63 0a  with a specific.
1cae0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61 74  **          [dat
1caf0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1cb00 5d 20 28 65 78 61 6d 70 6c 65 73 3a 0a 2a 2a 20  ] (examples:.** 
1cb10 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1cb20 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 6f 72 20  3_mprintf()] or 
1cb30 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
1cb40 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 0a  shared_cache()].
1cb50 2a 2a 20 20 20 20 20 20 20 20 20 20 64 6f 20 6e  **          do n
1cb60 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
1cb70 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
1cb80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1cb90 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1cba0 2c 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  , [sqlite3_errms
1cbb0 67 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  g()], or [sqlite
1cbc0 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a  3_errmsg16()]..*
1cbd0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
1cbe0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
1cbf0 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  b);.const char *
1cc00 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
1cc10 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20  qlite3*);.const 
1cc20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72  void *sqlite3_er
1cc30 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29  rmsg16(sqlite3*)
1cc40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1cc50 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
1cc60 20 4f 62 6a 65 63 74 20 7b 48 31 33 30 30 30 7d   Object {H13000}
1cc70 20 3c 48 31 33 30 31 30 3e 0a 2a 2a 20 4b 45 59   <H13010>.** KEY
1cc80 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64  WORDS: {prepared
1cc90 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65   statement} {pre
1cca0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
1ccb0 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
1ccc0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
1ccd0 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20  ct represents a 
1cce0 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65  single SQL state
1ccf0 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ment..** This ob
1cd00 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c  ject is variousl
1cd10 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72  y known as a "pr
1cd20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1cd30 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69  " or a.** "compi
1cd40 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  led SQL statemen
1cd50 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20  t" or simply as 
1cd60 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a  a "statement"..*
1cd70 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66  *.** The life of
1cd80 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a   a statement obj
1cd90 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69  ect goes somethi
1cda0 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ng like this:.**
1cdb0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
1cdc0 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65   Create the obje
1cdd0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
1cde0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1cdf0 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20  or a related.** 
1ce00 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a       function..*
1ce10 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
1ce20 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61  es to [host para
1ce30 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
1ce40 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1ce50 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
1ce60 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
1ce70 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
1ce80 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
1ce90 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
1cea0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
1ceb0 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61 74  > Reset the stat
1cec0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
1ced0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
1cee0 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
1cef0 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
1cf00 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
1cf10 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
1cf20 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
1cf30 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
1cf40 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1cf50 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
1cf60 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65   Refer to docume
1cf70 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  ntation on indiv
1cf80 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62  idual methods ab
1cf90 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ove for addition
1cfa0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
1cfb0 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
1cfc0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  ruct sqlite3_stm
1cfd0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a  t sqlite3_stmt;.
1cfe0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1cff0 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73   Run-time Limits
1d000 20 7b 48 31 32 37 36 30 7d 20 3c 53 32 30 36 30   {H12760} <S2060
1d010 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0>.**.** This in
1d020 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
1d030 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
1d040 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
1d050 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
1d060 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
1d070 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
1d080 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
1d090 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
1d0a0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1d0b0 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
1d0c0 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
1d0d0 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
1d0e0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1d0f0 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
1d100 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
1d110 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
1d120 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
1d130 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
1d140 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
1d150 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
1d160 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
1d170 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
1d180 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 54  at construct.  T
1d190 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  he function retu
1d1a0 72 6e 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69  rns the old limi
1d1b0 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
1d1c0 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
1d1d0 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
1d1e0 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
1d1f0 68 61 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74  hanged..** For t
1d200 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  he limit categor
1d210 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49  y of SQLITE_LIMI
1d220 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20 61  T_XYZ there is a
1d230 20 68 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 62   hard upper.** b
1d240 6f 75 6e 64 20 73 65 74 20 62 79 20 61 20 63 6f  ound set by a co
1d250 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20 70 72 65  mpile-time C pre
1d260 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
1d270 6e 61 6d 65 64 20 53 51 4c 49 54 45 5f 4d 41 58  named SQLITE_MAX
1d280 5f 58 59 5a 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  _XYZ..** (The "_
1d290 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
1d2a0 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
1d2b0 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41  o "_MAX_".).** A
1d2c0 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
1d2d0 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
1d2e0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
1d2f0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
1d300 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
1d310 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
1d320 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20  er limit..**.** 
1d330 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run time limits 
1d340 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
1d350 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
1d360 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
1d370 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
1d380 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
1d390 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
1d3a0 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
1d3b0 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
1d3c0 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
1d3d0 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
1d3e0 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
1d3f0 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
1d400 0a 2a 2a 20 77 65 62 62 72 6f 77 73 65 72 20 74  .** webbrowser t
1d410 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
1d420 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
1d430 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
1d440 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
1d450 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
1d460 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
1d470 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
1d480 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
1d490 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
1d4a0 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
1d4b0 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
1d4c0 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
1d4d0 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
1d4e0 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
1d4f0 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
1d500 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
1d510 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
1d520 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
1d530 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
1d540 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
1d550 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
1d560 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
1d570 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
1d580 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
1d590 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
1d5a0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
1d5b0 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
1d5c0 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
1d5d0 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
1d5e0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
1d5f0 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
1d600 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
1d610 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
1d620 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
1d630 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
1d640 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
1d650 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
1d660 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
1d670 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
1d680 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
1d690 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1d6a0 2a 20 7b 48 31 32 37 36 32 7d 20 41 20 73 75 63  * {H12762} A suc
1d6b0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
1d6c0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44  [sqlite3_limit(D
1d6d0 2c 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69  ,C,V)] where V i
1d6e0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f  s.**          po
1d6f0 73 69 74 69 76 65 20 63 68 61 6e 67 65 73 20 74  sitive changes t
1d700 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20  he limit on the 
1d710 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63  size of construc
1d720 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  t C in the.**   
1d730 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
1d740 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74   connection] D t
1d750 6f 20 74 68 65 20 6c 65 73 73 65 72 20 6f 66 20  o the lesser of 
1d760 56 20 61 6e 64 20 74 68 65 20 68 61 72 64 20 75  V and the hard u
1d770 70 70 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  pper.**         
1d780 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20 73 69   bound on the si
1d790 7a 65 20 6f 66 20 43 20 74 68 61 74 20 69 73 20  ze of C that is 
1d7a0 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
1d7b0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ime..**.** {H127
1d7c0 36 36 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  66} A successful
1d7d0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
1d7e0 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20  3_limit(D,C,V)] 
1d7f0 77 68 65 72 65 20 56 20 69 73 20 6e 65 67 61 74  where V is negat
1d800 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
1d810 6c 65 61 76 65 73 20 74 68 65 20 73 74 61 74 65  leaves the state
1d820 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
1d830 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
1d840 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a  unchanged..**.**
1d850 20 7b 48 31 32 37 36 39 7d 20 41 20 73 75 63 63   {H12769} A succ
1d860 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
1d870 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c  sqlite3_limit(D,
1d880 43 2c 56 29 5d 20 72 65 74 75 72 6e 73 20 74 68  C,V)] returns th
1d890 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  e.**          va
1d8a0 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
1d8b0 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20   on the size of 
1d8c0 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e 20 74  construct C in t
1d8d0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
1d8e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d8f0 69 6f 6e 5d 20 44 20 61 73 20 69 74 20 77 61 73  ion] D as it was
1d900 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61   prior to the ca
1d910 6c 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ll..*/.int sqlit
1d920 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
1d930 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
1d940 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
1d950 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1d960 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
1d970 65 73 20 7b 48 31 32 37 39 30 7d 20 3c 48 31 32  es {H12790} <H12
1d980 37 36 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  760>.** KEYWORDS
1d990 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
1d9a0 79 7d 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  y} {limit catego
1d9b0 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
1d9c0 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
1d9d0 6e 65 20 76 61 72 69 6f 75 73 20 61 73 70 65 63  ne various aspec
1d9e0 74 73 20 6f 66 20 61 20 5b 64 61 74 61 62 61 73  ts of a [databas
1d9f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
1da00 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 69 6d   that can be lim
1da10 69 74 65 64 20 69 6e 20 73 69 7a 65 20 62 79 20  ited in size by 
1da20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1da30 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
1da40 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
1da50 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
1da60 73 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73  s are as follows
1da70 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  :.**.** <dl>.** 
1da80 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1da90 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1daa0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1dab0 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
1dac0 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
1dad0 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a  ble row.<dd>.**.
1dae0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1daf0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
1db00 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1db10 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1db20 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1db30 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
1db40 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
1db50 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
1db60 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1db70 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
1db80 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
1db90 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
1dba0 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
1dbb0 20 61 20 53 45 4c 45 43 54 20 6f 72 20 74 68 65   a SELECT or the
1dbc0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
1dbd0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
1dbe0 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
1dbf0 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
1dc00 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
1dc10 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1dc20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
1dc30 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
1dc40 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
1dc50 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
1dc60 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
1dc70 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  pression.</dd>.*
1dc80 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1dc90 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
1dca0 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
1dcb0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1dcc0 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
1dcd0 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
1dce0 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
1dcf0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1dd00 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
1dd10 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
1dd20 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1dd30 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
1dd40 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
1dd50 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
1dd60 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1dd70 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
1dd80 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ent.</dd>.**.** 
1dd90 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1dda0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
1ddb0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1ddc0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1ddd0 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
1dde0 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a  unction.</dd>.**
1ddf0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1de00 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
1de10 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1de20 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1de30 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
1de40 65 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  es.</dd>.**.** <
1de50 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1de60 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
1de70 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
1de80 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
1de90 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
1dea0 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
1deb0 65 20 4c 49 4b 45 20 6f 72 0a 2a 2a 20 47 4c 4f  e LIKE or.** GLO
1dec0 42 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  B operators.</dd
1ded0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1dee0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
1def0 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
1df00 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1df10 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61   number of varia
1df20 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73  bles in an SQL s
1df30 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61  tatement that ca
1df40 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f  n.** be bound.</
1df50 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  dd>.** </dl>.*/.
1df60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1df70 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
1df80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
1df90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1dfa0 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
1dfb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1dfc0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
1dfd0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
1dfe0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1dff0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
1e000 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
1e010 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
1e020 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
1e030 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
1e040 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
1e050 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
1e060 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
1e070 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
1e080 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
1e090 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
1e0a0 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
1e0b0 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
1e0c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
1e0d0 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
1e0e0 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
1e0f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
1e100 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
1e110 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
1e120 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
1e130 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
1e140 20 20 20 20 20 20 20 20 39 0a 0a 2f 2a 0a 2a 2a          9../*.**
1e150 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
1e160 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74  ling An SQL Stat
1e170 65 6d 65 6e 74 20 7b 48 31 33 30 31 30 7d 20 3c  ement {H13010} <
1e180 53 31 30 30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S10000>.** KEYWO
1e190 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
1e1a0 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
1e1b0 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
1e1c0 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
1e1d0 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
1e1e0 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
1e1f0 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
1e200 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
1e210 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
1e220 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
1e230 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
1e240 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
1e250 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
1e260 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
1e270 69 6f 72 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ior call to [sql
1e280 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1e290 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1e2a0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
1e2b0 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  en16()]..**.** T
1e2c0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1e2d0 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74  nt, "zSql", is t
1e2e0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
1e2f0 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
1e300 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
1e310 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
1e320 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
1e330 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71  prepare() and sq
1e340 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e350 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
1e360 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20   use UTF-8, and 
1e370 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1e380 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  6() and sqlite3_
1e390 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a  prepare16_v2().*
1e3a0 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  * use UTF-16..**
1e3b0 0a 2a 2a 20 49 66 20 74 68 65 20 6e 42 79 74 65  .** If the nByte
1e3c0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73   argument is les
1e3d0 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  s than zero, the
1e3e0 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
1e3f0 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
1e400 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
1e410 72 2e 20 49 66 20 6e 42 79 74 65 20 69 73 20 6e  r. If nByte is n
1e420 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
1e430 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
1e440 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  mum.** number of
1e450 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f    bytes read fro
1e460 6d 20 7a 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42  m zSql.  When nB
1e470 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
1e480 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c  ive, the.** zSql
1e490 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20   string ends at 
1e4a0 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74  either the first
1e4b0 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30   '\000' or '\u00
1e4c0 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72  00' character or
1e4d0 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68  .** the nByte-th
1e4e0 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72   byte, whichever
1e4f0 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66   comes first. If
1e500 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
1e510 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75  s.** that the su
1e520 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
1e530 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
1e540 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61   then there is a
1e550 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72   small.** perfor
1e560 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
1e570 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20  to be gained by 
1e580 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
1e590 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
1e5a0 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74  ** is equal to t
1e5b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1e5c0 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20  es in the input 
1e5d0 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64  string <i>includ
1e5e0 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e  ing</i>.** the n
1e5f0 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79  ul-terminator by
1e600 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 2a 70 7a 54 61  tes..**.** *pzTa
1e610 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
1e620 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
1e630 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20 65   byte past the e
1e640 6e 64 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  nd of the.** fir
1e650 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
1e660 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
1e670 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 20 63   routines only c
1e680 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74  ompile the first
1e690 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
1e6a0 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
1e6b0 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
1e6c0 6e 67 20 74 6f 20 77 68 61 74 20 72 65 6d 61 69  ng to what remai
1e6d0 6e 73 0a 2a 2a 20 75 6e 63 6f 6d 70 69 6c 65 64  ns.** uncompiled
1e6e0 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d 74 20  ..**.** *ppStmt 
1e6f0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
1e700 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
1e710 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1e720 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
1e730 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
1e740 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
1e750 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  )].  If there is
1e760 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
1e770 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
1e780 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20 69 6e  NULL.  If the in
1e790 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e  put text contain
1e7a0 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65  s no SQL (if the
1e7b0 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70   input is an emp
1e7c0 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20  ty.** string or 
1e7d0 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20  a comment) then 
1e7e0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74  *ppStmt is set t
1e7f0 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 7b 41 31 33 30  o NULL..** {A130
1e800 31 38 7d 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  18} The calling 
1e810 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73  procedure is res
1e820 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c  ponsible for del
1e830 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  eting the compil
1e840 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
1e850 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
1e860 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
1e870 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
1e880 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
1e890 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20  .** On success, 
1e8a0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
1e8b0 65 74 75 72 6e 65 64 2c 20 6f 74 68 65 72 77 69  eturned, otherwi
1e8c0 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
1e8d0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
1e8e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1e8f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
1e900 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1e910 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
1e920 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
1e930 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
1e940 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
1e950 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
1e960 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
1e970 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
1e980 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1e990 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
1e9a0 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
1e9b0 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 22 76 32 22  ..** In the "v2"
1e9c0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
1e9d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
1e9e0 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72  ent.** that is r
1e9f0 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71  eturned (the [sq
1ea00 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
1ea10 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63  ct) contains a c
1ea20 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72  opy of the.** or
1ea30 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e  iginal SQL text.
1ea40 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65   This causes the
1ea50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1ea60 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a  ] interface to.*
1ea70 2a 20 62 65 68 61 76 65 20 61 20 64 69 66 66 65  * behave a diffe
1ea80 72 65 6e 74 6c 79 20 69 6e 20 74 77 6f 20 77 61  rently in two wa
1ea90 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  ys:.**.** <ol>.*
1eaa0 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66 20 74 68 65  * <li>.** If the
1eab0 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
1eac0 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
1ead0 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
1eae0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
1eaf0 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
1eb00 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
1eb10 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
1eb20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
1eb30 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
1eb40 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
1eb50 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
1eb60 61 67 61 69 6e 2e 20 20 49 66 20 74 68 65 20 73  again.  If the s
1eb70 63 68 65 6d 61 20 68 61 73 20 63 68 61 6e 67 65  chema has change
1eb80 64 20 69 6e 0a 2a 2a 20 61 20 77 61 79 20 74 68  d in.** a way th
1eb90 61 74 20 6d 61 6b 65 73 20 74 68 65 20 73 74 61  at makes the sta
1eba0 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f 6e 67 65 72  tement no longer
1ebb0 20 76 61 6c 69 64 2c 20 5b 73 71 6c 69 74 65 33   valid, [sqlite3
1ebc0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 73 74  _step()] will st
1ebd0 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
1ebe0 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2e 20 20  QLITE_SCHEMA].  
1ebf0 42 75 74 20 75 6e 6c 69 6b 65 20 74 68 65 20 6c  But unlike the l
1ec00 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2c 20  egacy behavior, 
1ec10 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20  [SQLITE_SCHEMA] 
1ec20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20 66 61 74 61  is.** now a fata
1ec30 6c 20 65 72 72 6f 72 2e 20 20 43 61 6c 6c 69 6e  l error.  Callin
1ec40 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1ec50 72 65 5f 76 32 28 29 5d 20 61 67 61 69 6e 20 77  re_v2()] again w
1ec60 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65 20 74 68 65  ill not make the
1ec70 0a 2a 2a 20 65 72 72 6f 72 20 67 6f 20 61 77 61  .** error go awa
1ec80 79 2e 20 20 4e 6f 74 65 3a 20 75 73 65 20 5b 73  y.  Note: use [s
1ec90 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
1eca0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 65 78   to find the tex
1ecb0 74 0a 2a 2a 20 6f 66 20 74 68 65 20 70 61 72 73  t.** of the pars
1ecc0 69 6e 67 20 65 72 72 6f 72 20 74 68 61 74 20 72  ing error that r
1ecd0 65 73 75 6c 74 73 20 69 6e 20 61 6e 20 5b 53 51  esults in an [SQ
1ece0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 72 65 74  LITE_SCHEMA] ret
1ecf0 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  urn..** </li>.**
1ed00 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 57 68 65 6e  .** <li>.** When
1ed10 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1ed20 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1ed30 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
1ed40 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
1ed50 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
1ed60 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
1ed70 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
1ed80 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  The legacy behav
1ed90 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20  ior was that.** 
1eda0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1edb0 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75   would only retu
1edc0 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51  rn a generic [SQ
1edd0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75  LITE_ERROR] resu
1ede0 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 79  lt code.** and y
1edf0 6f 75 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  ou would have to
1ee00 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
1ee10 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
1ee20 72 65 73 65 74 28 29 5d 20 69 6e 20 6f 72 64 65  reset()] in orde
1ee30 72 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65  r.** to find the
1ee40 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
1ee50 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
1ee60 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
1ee70 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
1ee80 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
1ee90 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
1eea0 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
1eeb0 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
1eec0 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  ly..** </li>.** 
1eed0 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  </ol>.**.** INVA
1eee0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
1eef0 31 33 30 31 31 7d 20 54 68 65 20 5b 73 71 6c 69  13011} The [sqli
1ef00 74 65 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a  te3_prepare(db,z
1ef10 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a  Sql,...)] and.**
1ef20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
1ef30 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62  e3_prepare_v2(db
1ef40 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65  ,zSql,...)] inte
1ef50 72 66 61 63 65 73 20 69 6e 74 65 72 70 72 65 74  rfaces interpret
1ef60 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
1ef70 20 74 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a   text in their z
1ef80 53 71 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73  Sql parameter as
1ef90 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48   UTF-8..**.** {H
1efa0 31 33 30 31 32 7d 20 54 68 65 20 5b 73 71 6c 69  13012} The [sqli
1efb0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 64 62  te3_prepare16(db
1efc0 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20 61 6e 64 0a  ,zSql,...)] and.
1efd0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
1efe0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1eff0 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20  2(db,zSql,...)] 
1f000 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74 65 72  interfaces inter
1f010 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  pret the.**     
1f020 20 20 20 20 20 74 65 78 74 20 69 6e 20 74 68 65       text in the
1f030 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65 74 65  ir zSql paramete
1f040 72 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  r as UTF-16 in t
1f050 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
1f060 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  rder..**.** {H13
1f070 30 31 33 7d 20 49 66 20 74 68 65 20 6e 42 79 74  013} If the nByt
1f080 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  e argument to [s
1f090 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1f0a0 32 28 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c  2(db,zSql,nByte,
1f0b0 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
1f0c0 20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e    and its varian
1f0d0 74 73 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  ts is less than 
1f0e0 7a 65 72 6f 2c 20 74 68 65 20 53 51 4c 20 74 65  zero, the SQL te
1f0f0 78 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20  xt is.**        
1f100 20 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c    read from zSql
1f110 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
1f120 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
1f130 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
1f140 7b 48 31 33 30 31 34 7d 20 49 66 20 74 68 65 20  {H13014} If the 
1f150 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 74  nByte argument t
1f160 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
1f170 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 6e 42  re_v2(db,zSql,nB
1f180 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  yte,...)].**    
1f190 20 20 20 20 20 20 61 6e 64 20 69 74 73 20 76 61        and its va
1f1a0 72 69 61 6e 74 73 20 69 73 20 6e 6f 6e 2d 6e 65  riants is non-ne
1f1b0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 74 20  gative, then at 
1f1c0 6d 6f 73 74 20 6e 42 79 74 65 73 20 62 79 74 65  most nBytes byte
1f1d0 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  s of.**         
1f1e0 20 53 51 4c 20 74 65 78 74 20 69 73 20 72 65 61   SQL text is rea
1f1f0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 0a 2a 2a 0a  d from zSql..**.
1f200 2a 2a 20 7b 48 31 33 30 31 35 7d 20 49 6e 20 5b  ** {H13015} In [
1f210 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1f220 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 50 2c 70  v2(db,zSql,N,P,p
1f230 7a 54 61 69 6c 29 5d 20 61 6e 64 20 69 74 73 20  zTail)] and its 
1f240 76 61 72 69 61 6e 74 73 0a 2a 2a 20 20 20 20 20  variants.**     
1f250 20 20 20 20 20 69 66 20 74 68 65 20 7a 53 71 6c       if the zSql
1f260 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
1f270 61 69 6e 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  ains more than o
1f280 6e 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ne SQL statement
1f290 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
1f2a0 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
1f2b0 55 4c 4c 2c 20 74 68 65 6e 20 2a 70 7a 54 61 69  ULL, then *pzTai
1f2c0 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
1f2d0 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  nt to the.**    
1f2e0 20 20 20 20 20 20 66 69 72 73 74 20 62 79 74 65        first byte
1f2f0 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
1f300 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
1f310 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
1f320 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74  ..**          <t
1f330 6f 64 6f 3e 57 68 61 74 20 64 6f 65 73 20 2a 70  odo>What does *p
1f340 7a 54 61 69 6c 20 70 6f 69 6e 74 20 74 6f 20 69  zTail point to i
1f350 66 20 74 68 65 72 65 20 69 73 20 6f 6e 65 20 73  f there is one s
1f360 74 61 74 65 6d 65 6e 74 3f 3c 2f 74 6f 64 6f 3e  tatement?</todo>
1f370 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 36 7d 20  .**.** {H13016} 
1f380 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
1f390 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  l to [sqlite3_pr
1f3a0 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c  epare_v2(db,zSql
1f3b0 2c 4e 2c 70 70 53 74 6d 74 2c 2e 2e 2e 29 5d 0a  ,N,ppStmt,...)].
1f3c0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 6f  **          or o
1f3d0 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
1f3e0 74 73 20 77 72 69 74 65 73 20 69 6e 74 6f 20 2a  ts writes into *
1f3f0 70 70 53 74 6d 74 20 61 20 70 6f 69 6e 74 65 72  ppStmt a pointer
1f400 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20   to a new.**    
1f410 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
1f420 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 61 20  statement] or a 
1f430 70 6f 69 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20  pointer to NULL 
1f440 69 66 20 7a 53 71 6c 20 63 6f 6e 74 61 69 6e 73  if zSql contains
1f450 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 74  .**          not
1f460 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
1f470 77 68 69 74 65 73 70 61 63 65 20 6f 72 20 63 6f  whitespace or co
1f480 6d 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  mments..**.** {H
1f490 31 33 30 31 39 7d 20 54 68 65 20 5b 73 71 6c 69  13019} The [sqli
1f4a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f4b0 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20  ] interface and 
1f4c0 69 74 73 20 76 61 72 69 61 6e 74 73 20 72 65 74  its variants ret
1f4d0 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
1f4e0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 61  [SQLITE_OK] or a
1f4f0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
1f500 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 20  rror code] upon 
1f510 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b  failure..**.** {
1f520 48 31 33 30 32 31 7d 20 42 65 66 6f 72 65 20 5b  H13021} Before [
1f530 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1f540 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 70 70  db,zSql,nByte,pp
1f550 53 74 6d 74 2c 70 7a 54 61 69 6c 29 5d 20 6f 72  Stmt,pzTail)] or
1f560 20 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20   its.**         
1f570 20 76 61 72 69 61 6e 74 73 20 72 65 74 75 72 6e   variants return
1f580 73 20 61 6e 20 65 72 72 6f 72 20 28 61 6e 79 20  s an error (any 
1f590 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
1f5a0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 29 2c 0a 2a   [SQLITE_OK]),.*
1f5b0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 79 20  *          they 
1f5c0 66 69 72 73 74 20 73 65 74 20 2a 70 70 53 74 6d  first set *ppStm
1f5d0 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  t to NULL..*/.in
1f5e0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1f5f0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
1f600 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1f610 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1f620 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1f630 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1f640 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1f650 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
1f660 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
1f670 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
1f680 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
1f690 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
1f6a0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
1f6b0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
1f6c0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
1f6d0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
1f6e0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
1f6f0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
1f700 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
1f710 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
1f720 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
1f730 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
1f740 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1f750 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1f760 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1f770 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1f780 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1f790 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
1f7a0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1f7b0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1f7c0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1f7d0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1f7e0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1f7f0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1f800 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1f810 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1f820 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
1f830 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1f840 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1f850 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1f860 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1f870 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
1f880 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1f890 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1f8a0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1f8b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
1f8c0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1f8d0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
1f8e0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1f8f0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1f900 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1f910 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1f920 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1f930 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1f940 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1f950 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1f960 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1f970 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1f980 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1f990 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1f9a0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
1f9b0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1f9c0 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
1f9d0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
1f9e0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
1f9f0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
1fa00 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
1fa10 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
1fa20 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
1fa30 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1fa40 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1fa50 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1fa60 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1fa70 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1fa80 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1fa90 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1faa0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1fab0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
1fac0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1fad0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1fae0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1faf0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
1fb00 49 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  IREF: Retrieving
1fb10 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 20 7b   Statement SQL {
1fb20 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30 30 3e  H13100} <H13000>
1fb30 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1fb40 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
1fb50 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20  d to retrieve a 
1fb60 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68  saved copy of th
1fb70 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51  e original.** SQ
1fb80 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
1fb90 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65  reate a [prepare
1fba0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20  d statement] if 
1fbb0 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77  that statement w
1fbc0 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75  as.** compiled u
1fbd0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
1fbe0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1fbf0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
1fc00 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
1fc10 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
1fc20 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 31 7d  :.**.** {H13101}
1fc30 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   If the [prepare
1fc40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70 61 73  d statement] pas
1fc50 73 65 64 20 61 73 20 74 68 65 20 61 72 67 75 6d  sed as the argum
1fc60 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ent to.**       
1fc70 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28     [sqlite3_sql(
1fc80 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  )] was compiled 
1fc90 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
1fca0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1fcb0 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ()] or.**       
1fcc0 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
1fcd0 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 74 68 65  are16_v2()], the
1fce0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29  n [sqlite3_sql()
1fcf0 5d 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  ] returns.**    
1fd00 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20        a pointer 
1fd10 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
1fd20 61 74 65 64 20 73 74 72 69 6e 67 20 63 6f 6e 74  ated string cont
1fd30 61 69 6e 69 6e 67 20 61 20 55 54 46 2d 38 20 72  aining a UTF-8 r
1fd40 65 6e 64 65 72 69 6e 67 0a 2a 2a 20 20 20 20 20  endering.**     
1fd50 20 20 20 20 20 6f 66 20 74 68 65 20 6f 72 69 67       of the orig
1fd60 69 6e 61 6c 20 53 51 4c 20 73 74 61 74 65 6d 65  inal SQL stateme
1fd70 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30  nt..**.** {H1310
1fd80 32 7d 20 49 66 20 74 68 65 20 5b 70 72 65 70 61  2} If the [prepa
1fd90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 70  red statement] p
1fda0 61 73 73 65 64 20 61 73 20 74 68 65 20 61 72 67  assed as the arg
1fdb0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20  ument to.**     
1fdc0 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73 71       [sqlite3_sq
1fdd0 6c 28 29 5d 20 77 61 73 20 63 6f 6d 70 69 6c 65  l()] was compile
1fde0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  d using either [
1fdf0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1fe00 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
1fe10 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61    [sqlite3_prepa
1fe20 72 65 31 36 28 29 5d 2c 20 74 68 65 6e 20 5b 73  re16()], then [s
1fe30 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 72 65  qlite3_sql()] re
1fe40 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1fe50 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  nter..**.** {H13
1fe60 31 30 33 7d 20 54 68 65 20 73 74 72 69 6e 67 20  103} The string 
1fe70 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1fe80 69 74 65 33 5f 73 71 6c 28 53 29 5d 20 69 73 20  ite3_sql(S)] is 
1fe90 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 0a  valid until the.
1fea0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
1feb0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1fec0 20 53 20 69 73 20 64 65 6c 65 74 65 64 20 75 73   S is deleted us
1fed0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
1fee0 61 6c 69 7a 65 28 53 29 5d 2e 0a 2a 2f 0a 63 6f  alize(S)]..*/.co
1fef0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1ff00 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  3_sql(sqlite3_st
1ff10 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
1ff20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
1ff30 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
1ff40 61 6c 75 65 20 4f 62 6a 65 63 74 20 7b 48 31 35  alue Object {H15
1ff50 30 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  000} <S20200>.**
1ff60 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74   KEYWORDS: {prot
1ff70 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1ff80 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65  lue} {unprotecte
1ff90 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
1ffa0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
1ffb0 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  es the sqlite3_v
1ffc0 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72  alue object to r
1ffd0 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c  epresent all val
1ffe0 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  ues.** that can 
1fff0 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64  be stored in a d
20000 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53  atabase table. S
20010 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
20020 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72  ic typing.** for
20030 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73   the values it s
20040 74 6f 72 65 73 2e 20 56 61 6c 75 65 73 20 73 74  tores. Values st
20050 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
20060 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
20070 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
20080 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
20090 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
200a0 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
200b0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
200c0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
200d0 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
200e0 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
200f0 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
20100 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
20110 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
20120 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
20130 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
20140 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
20150 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
20160 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
20170 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
20180 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
20190 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
201a0 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
201b0 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
201c0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
201d0 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
201e0 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
201f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
20200 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
20210 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
20220 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
20230 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
20240 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
20250 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69  ex is held.  A i
20260 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
20270 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
20280 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
20290 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
202a0 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
202b0 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
202c0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
202d0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
202e0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
202f0 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
20300 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
20310 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
20320 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
20330 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
20340 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
20350 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
20360 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
20370 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
20380 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
20390 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
203a0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
203b0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
203c0 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
203d0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
203e0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
203f0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
20400 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
20410 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
20420 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
20430 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
20440 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
20450 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
20460 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
20470 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
20480 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
20490 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
204a0 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
204b0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
204c0 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
204d0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
204e0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
204f0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65  alue objects eve
20500 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63  n when not stric
20510 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  tly required..**
20520 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
20530 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68  value objects th
20540 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73  at are passed as
20550 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f   parameters into
20560 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
20570 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69  tation of [appli
20580 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
20590 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72  QL functions] ar
205a0 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  e protected..** 
205b0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
205c0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
205d0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
205e0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
205f0 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
20600 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
20610 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
20620 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
20630 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
20640 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
20650 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
20660 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
20670 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
20680 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
20690 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
206a0 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
206b0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
206c0 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
206d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
206e0 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
206f0 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
20700 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
20710 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
20720 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
20730 78 74 20 4f 62 6a 65 63 74 20 7b 48 31 36 30 30  xt Object {H1600
20740 31 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a  1} <S20200>.**.*
20750 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e  * The context in
20760 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75   which an SQL fu
20770 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20  nction executes 
20780 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a  is stored in an.
20790 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ** sqlite3_conte
207a0 78 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f  xt object.  A po
207b0 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69  inter to an sqli
207c0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
207d0 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ct.** is always 
207e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
207f0 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  to [application-
20800 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
20810 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  tions]..** The a
20820 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
20830 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
20840 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
20850 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a  ill pass this.**
20860 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68   pointer through
20870 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b   into calls to [
20880 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
20890 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73  nt | sqlite3_res
208a0 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ult()],.** [sqli
208b0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
208c0 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74  ntext()], [sqlit
208d0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c  e3_user_data()],
208e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
208f0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
20900 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ], [sqlite3_get_
20910 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61  auxdata()],.** a
20920 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  nd/or [sqlite3_s
20930 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a  et_auxdata()]..*
20940 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
20950 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
20960 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
20970 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20980 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65  F: Binding Value
20990 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74  s To Prepared St
209a0 61 74 65 6d 65 6e 74 73 20 7b 48 31 33 35 30 30  atements {H13500
209b0 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 20 4b 45  } <S70300>.** KE
209c0 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61  YWORDS: {host pa
209d0 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70  rameter} {host p
209e0 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74  arameters} {host
209f0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d   parameter name}
20a00 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
20a10 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53  QL parameter} {S
20a20 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  QL parameters} {
20a30 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
20a40 67 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  g}.**.** In the 
20a50 53 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 75  SQL strings inpu
20a60 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
20a70 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
20a80 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
20a90 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
20aa0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 70   replaced by a p
20ab0 61 72 61 6d 65 74 65 72 20 69 6e 20 6f 6e 65 20  arameter in one 
20ac0 6f 66 20 74 68 65 73 65 20 66 6f 72 6d 73 3a 0a  of these forms:.
20ad0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
20ae0 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
20af0 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56  NNN.** <li>  :VV
20b00 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a  V.** <li>  @VVV.
20b10 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
20b20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
20b30 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 66 6f  the parameter fo
20b40 72 6d 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  rms shown above 
20b50 4e 4e 4e 20 69 73 20 61 6e 20 69 6e 74 65 67 65  NNN is an intege
20b60 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
20b70 64 20 56 56 56 20 69 73 20 61 6e 20 61 6c 70 68  d VVV is an alph
20b80 61 2d 6e 75 6d 65 72 69 63 20 70 61 72 61 6d 65  a-numeric parame
20b90 74 65 72 20 6e 61 6d 65 2e 20 54 68 65 20 76 61  ter name. The va
20ba0 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
20bb0 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
20bc0 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
20bd0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
20be0 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
20bf0 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
20c00 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
20c10 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
20c20 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
20c30 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ere..**.** The f
20c40 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
20c50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
20c60 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69  d_*() routines i
20c70 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f  s always.** a po
20c80 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
20c90 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
20ca0 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
20cb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
20cc0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
20cd0 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a  s variants..**.*
20ce0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
20cf0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
20d00 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61  ex of the SQL pa
20d10 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65  rameter to be se
20d20 74 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 74 6d 6f  t..** The leftmo
20d30 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
20d40 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
20d50 20 31 2e 20 20 57 68 65 6e 20 74 68 65 20 73 61   1.  When the sa
20d60 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
20d70 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
20d80 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
20d90 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
20da0 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
20db0 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
20dc0 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
20dd0 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
20de0 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78  ce..** The index
20df0 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
20e00 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
20e10 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
20e20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
20e30 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
20e40 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
20e50 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a  red.  The index.
20e60 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
20e70 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
20e80 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
20e90 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d   The NNN value m
20ea0 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
20eb0 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
20ec0 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
20ed0 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
20ee0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
20ef0 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
20f00 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
20f10 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67  ** The third arg
20f20 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
20f30 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
20f40 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  e parameter..**.
20f50 2a 2a 20 49 6e 20 74 68 6f 73 65 20 72 6f 75 74  ** In those rout
20f60 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
20f70 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
20f80 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
20f90 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
20fa0 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
20fb0 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
20fc0 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
20fd0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
20fe0 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
20ff0 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
21000 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
21010 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
21020 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
21030 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74  rameter is negat
21040 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20  ive, the length 
21050 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
21060 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
21070 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
21080 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
21090 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  minator..**.** T
210a0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
210b0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
210c0 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  d_blob(), sqlite
210d0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61  3_bind_text(), a
210e0 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  nd.** sqlite3_bi
210f0 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61  nd_text16() is a
21100 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
21110 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
21120 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74  he BLOB or.** st
21130 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74  ring after SQLit
21140 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  e has finished w
21150 69 74 68 20 69 74 2e 20 49 66 20 74 68 65 20 66  ith it. If the f
21160 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
21170 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
21180 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
21190 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69  ATIC], then SQLi
211a0 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
211b0 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  the.** informati
211c0 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  on is in static,
211d0 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
211e0 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
211f0 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a  ed to be freed..
21200 2a 2a 20 49 66 20 74 68 65 20 66 69 66 74 68 20  ** If the fifth 
21210 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
21220 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
21230 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
21240 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
21250 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
21260 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
21270 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
21280 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
21290 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
212a0 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
212b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
212c0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
212d0 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
212e0 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
212f0 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
21300 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
21310 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73   A zeroblob uses
21320 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20   a fixed amount 
21330 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75  of memory.** (ju
21340 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f  st an integer to
21350 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20   hold its size) 
21360 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
21370 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
21380 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
21390 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
213a0 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  as placeholders 
213b0 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a  for BLOBs whose.
213c0 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61  ** content is la
213d0 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e  ter written usin
213e0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  g.** [sqlite3_bl
213f0 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
21400 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
21410 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e  routines..** A n
21420 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f  egative value fo
21430 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
21440 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
21450 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
21460 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
21470 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
21480 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
21490 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74   after.** [sqlit
214a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
214b0 20 28 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e   (and its varian
214c0 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ts) or [sqlite3_
214d0 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20  reset()] and.** 
214e0 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f  before [sqlite3_
214f0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64  step()]..** Bind
21500 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65  ings are not cle
21510 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ared by the [sql
21520 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f  ite3_reset()] ro
21530 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e  utine..** Unboun
21540 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
21550 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
21560 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  NULL..**.** Thes
21570 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
21580 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
21590 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65   success or an e
215a0 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20  rror code if.** 
215b0 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
215c0 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41  ong.  [SQLITE_RA
215d0 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
215e0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
215f0 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
21600 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53 51  t of range.  [SQ
21610 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
21620 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
21630 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53  c() fails..** [S
21640 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69  QLITE_MISUSE] mi
21650 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
21660 69 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  if these routine
21670 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20  s are called on 
21680 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d 61 63  a.** virtual mac
21690 68 69 6e 65 20 74 68 61 74 20 69 73 20 74 68 65  hine that is the
216a0 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f 72 20   wrong state or 
216b0 77 68 69 63 68 20 68 61 73 20 61 6c 72 65 61 64  which has alread
216c0 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  y been finalized
216d0 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f  ..** Detection o
216e0 66 20 6d 69 73 75 73 65 20 69 73 20 75 6e 72 65  f misuse is unre
216f0 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c 69 63 61  liable.  Applica
21700 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
21710 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51   depend.** on SQ
21720 4c 49 54 45 5f 4d 49 53 55 53 45 20 72 65 74 75  LITE_MISUSE retu
21730 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53  rns.  SQLITE_MIS
21740 55 53 45 20 69 73 20 69 6e 74 65 6e 64 65 64 20  USE is intended 
21750 74 6f 20 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a  to indicate a.**
21760 20 61 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69   a logic error i
21770 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  n the applicatio
21780 6e 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  n.  Future versi
21790 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
217a0 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74  ght.** panic rat
217b0 68 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e 20  her than return 
217c0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a  SQLITE_MISUSE..*
217d0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
217e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
217f0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
21800 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
21810 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
21820 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
21830 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
21840 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _index()]..**.**
21850 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
21860 2a 2a 20 7b 48 31 33 35 30 36 7d 20 54 68 65 20  ** {H13506} The 
21870 5b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63  [SQL statement c
21880 6f 6d 70 69 6c 65 72 5d 20 72 65 63 6f 67 6e 69  ompiler] recogni
21890 7a 65 73 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  zes tokens of th
218a0 65 20 66 6f 72 6d 73 0a 2a 2a 20 20 20 20 20 20  e forms.**      
218b0 20 20 20 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c      "?", "?NNN",
218c0 20 22 24 56 56 56 22 2c 20 22 3a 56 56 56 22 2c   "$VVV", ":VVV",
218d0 20 61 6e 64 20 22 40 56 56 56 22 20 61 73 20 53   and "@VVV" as S
218e0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2c 0a 2a  QL parameters,.*
218f0 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72 65  *          where
21900 20 4e 4e 4e 20 69 73 20 61 6e 79 20 73 65 71 75   NNN is any sequ
21910 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  ence of one or m
21920 6f 72 65 20 64 69 67 69 74 73 0a 2a 2a 20 20 20  ore digits.**   
21930 20 20 20 20 20 20 20 61 6e 64 20 77 68 65 72 65         and where
21940 20 56 56 56 20 69 73 20 61 6e 79 20 73 65 71 75   VVV is any sequ
21950 65 6e 63 65 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  ence of one or m
21960 6f 72 65 20 61 6c 70 68 61 6e 75 6d 65 72 69 63  ore alphanumeric
21970 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 68 61  .**          cha
21980 72 61 63 74 65 72 73 20 6f 72 20 22 3a 3a 22 20  racters or "::" 
21990 6f 70 74 69 6f 6e 61 6c 6c 79 20 66 6f 6c 6c 6f  optionally follo
219a0 77 65 64 20 62 79 20 61 20 73 74 72 69 6e 67 20  wed by a string 
219b0 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20 20 20  containing.**   
219c0 20 20 20 20 20 20 20 6e 6f 20 73 70 61 63 65 73         no spaces
219d0 20 61 6e 64 20 63 6f 6e 74 61 69 6e 65 64 20 77   and contained w
219e0 69 74 68 69 6e 20 70 61 72 65 6e 74 68 65 73 65  ithin parenthese
219f0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 39  s..**.** {H13509
21a00 7d 20 54 68 65 20 69 6e 69 74 69 61 6c 20 76 61  } The initial va
21a10 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  lue of an SQL pa
21a20 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 2e  rameter is NULL.
21a30 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 32 7d 20  .**.** {H13512} 
21a40 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  The index of an 
21a50 22 3f 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65  "?" SQL paramete
21a60 72 20 69 73 20 6f 6e 65 20 6c 61 72 67 65 72 20  r is one larger 
21a70 74 68 61 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  than the.**     
21a80 20 20 20 20 20 6c 61 72 67 65 73 74 20 69 6e 64       largest ind
21a90 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61 6d 65  ex of SQL parame
21aa0 74 65 72 20 74 6f 20 74 68 65 20 6c 65 66 74 2c  ter to the left,
21ab0 20 6f 72 20 31 20 69 66 0a 2a 2a 20 20 20 20 20   or 1 if.**     
21ac0 20 20 20 20 20 74 68 65 20 22 3f 22 20 69 73 20       the "?" is 
21ad0 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  the leftmost SQL
21ae0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
21af0 2a 20 7b 48 31 33 35 31 35 7d 20 54 68 65 20 69  * {H13515} The i
21b00 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 4e 4e 4e  ndex of an "?NNN
21b10 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  " SQL parameter 
21b20 69 73 20 74 68 65 20 69 6e 74 65 67 65 72 20 4e  is the integer N
21b30 4e 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31  NN..**.** {H1351
21b40 38 7d 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20  8} The index of 
21b50 61 6e 20 22 3a 56 56 56 22 2c 20 22 24 56 56 56  an ":VVV", "$VVV
21b60 22 2c 20 6f 72 20 22 40 56 56 56 22 20 53 51 4c  ", or "@VVV" SQL
21b70 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
21b80 20 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61            the sa
21b90 6d 65 20 61 73 20 74 68 65 20 69 6e 64 65 78 20  me as the index 
21ba0 6f 66 20 6c 65 66 74 6d 6f 73 74 20 6f 63 63 75  of leftmost occu
21bb0 72 72 65 6e 63 65 73 20 6f 66 20 74 68 65 20 73  rrences of the s
21bc0 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
21bd0 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 20 6f 6e  parameter, or on
21be0 65 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 65 20  e more than the 
21bf0 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 76  largest index ov
21c00 65 72 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20  er all.**       
21c10 20 20 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f     parameters to
21c20 20 74 68 65 20 6c 65 66 74 20 69 66 20 74 68 69   the left if thi
21c30 73 20 69 73 20 74 68 65 20 66 69 72 73 74 20 6f  s is the first o
21c40 63 63 75 72 72 65 6e 63 65 0a 2a 2a 20 20 20 20  ccurrence.**    
21c50 20 20 20 20 20 20 6f 66 20 74 68 69 73 20 70 61        of this pa
21c60 72 61 6d 65 74 65 72 2c 20 6f 72 20 31 20 69 66  rameter, or 1 if
21c70 20 74 68 69 73 20 69 73 20 74 68 65 20 6c 65 66   this is the lef
21c80 74 6d 6f 73 74 20 70 61 72 61 6d 65 74 65 72 2e  tmost parameter.
21c90 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 31 7d 20  .**.** {H13521} 
21ca0 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65 6d 65  The [SQL stateme
21cb0 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 66 61 69  nt compiler] fai
21cc0 6c 73 20 77 69 74 68 20 61 6e 20 5b 53 51 4c 49  ls with an [SQLI
21cd0 54 45 5f 52 41 4e 47 45 5d 0a 2a 2a 20 20 20 20  TE_RANGE].**    
21ce0 20 20 20 20 20 20 65 72 72 6f 72 20 69 66 20 74        error if t
21cf0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
21d00 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
21d10 6c 65 73 73 20 74 68 61 6e 20 31 0a 2a 2a 20 20  less than 1.**  
21d20 20 20 20 20 20 20 20 20 6f 72 20 67 72 65 61 74          or great
21d30 65 72 20 74 68 61 6e 20 74 68 65 20 63 6f 6d 70  er than the comp
21d40 69 6c 65 2d 74 69 6d 65 20 53 51 4c 49 54 45 5f  ile-time SQLITE_
21d50 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MAX_VARIABLE_NUM
21d60 42 45 52 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  BER.**          
21d70 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
21d80 20 7b 48 31 33 35 32 34 7d 20 43 61 6c 6c 73 20   {H13524} Calls 
21d90 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
21da0 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f  _text | sqlite3_
21db0 62 69 6e 64 28 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d  bind(S,N,V,...)]
21dc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 73  .**          ass
21dd0 6f 63 69 61 74 65 20 74 68 65 20 76 61 6c 75 65  ociate the value
21de0 20 56 20 77 69 74 68 20 61 6c 6c 20 53 51 4c 20   V with all SQL 
21df0 70 61 72 61 6d 65 74 65 72 73 20 68 61 76 69 6e  parameters havin
21e00 67 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  g an.**         
21e10 20 69 6e 64 65 78 20 6f 66 20 4e 20 69 6e 20 74   index of N in t
21e20 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
21e30 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a  tement] S..**.**
21e40 20 7b 48 31 33 35 32 37 7d 20 43 61 6c 6c 73 20   {H13527} Calls 
21e50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
21e60 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f  _text | sqlite3_
21e70 62 69 6e 64 28 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a  bind(S,N,...)].*
21e80 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65 72 72  *          overr
21e90 69 64 65 20 70 72 69 6f 72 20 63 61 6c 6c 73 20  ide prior calls 
21ea0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 76 61  with the same va
21eb0 6c 75 65 73 20 6f 66 20 53 20 61 6e 64 20 4e 2e  lues of S and N.
21ec0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 30 7d 20  .**.** {H13530} 
21ed0 42 69 6e 64 69 6e 67 73 20 65 73 74 61 62 6c 69  Bindings establi
21ee0 73 68 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  shed by [sqlite3
21ef0 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71 6c  _bind_text | sql
21f00 69 74 65 33 5f 62 69 6e 64 28 53 2c 2e 2e 2e 29  ite3_bind(S,...)
21f10 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 65  ].**          pe
21f20 72 73 69 73 74 20 61 63 72 6f 73 73 20 63 61 6c  rsist across cal
21f30 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
21f40 65 73 65 74 28 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20  eset(S)]..**.** 
21f50 7b 48 31 33 35 33 33 7d 20 49 6e 20 63 61 6c 6c  {H13533} In call
21f60 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  s to [sqlite3_bi
21f70 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c  nd_blob(S,N,V,L,
21f80 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
21f90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
21fa0 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c  ext(S,N,V,L,D)],
21fb0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
21fc0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
21fd0 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  xt16(S,N,V,L,D)]
21fe0 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20 74 68   SQLite binds th
21ff0 65 20 66 69 72 73 74 20 4c 0a 2a 2a 20 20 20 20  e first L.**    
22000 20 20 20 20 20 20 62 79 74 65 73 20 6f 66 20 74        bytes of t
22010 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
22020 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  g pointed to by 
22030 56 2c 20 77 68 65 6e 20 4c 0a 2a 2a 20 20 20 20  V, when L.**    
22040 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 6e 65 67        is non-neg
22050 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ative..**.** {H1
22060 33 35 33 36 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3536} In calls t
22070 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
22080 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  text(S,N,V,L,D)]
22090 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
220a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65  [sqlite3_bind_te
220b0 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  xt16(S,N,V,L,D)]
220c0 20 53 51 4c 69 74 65 20 62 69 6e 64 73 20 63 68   SQLite binds ch
220d0 61 72 61 63 74 65 72 73 0a 2a 2a 20 20 20 20 20  aracters.**     
220e0 20 20 20 20 20 66 72 6f 6d 20 56 20 74 68 72 6f       from V thro
220f0 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
22100 72 6f 20 63 68 61 72 61 63 74 65 72 20 77 68 65  ro character whe
22110 6e 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e  n L is negative.
22120 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 39 7d 20  .**.** {H13539} 
22130 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
22140 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53  ite3_bind_blob(S
22150 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20  ,N,V,L,D)],.**  
22160 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
22170 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56  _bind_text(S,N,V
22180 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  ,L,D)], or.**   
22190 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
221a0 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c  bind_text16(S,N,
221b0 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20 69  V,L,D)] when D i
221c0 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a 2a  s the special.**
221d0 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74 61            consta
221e0 6e 74 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  nt [SQLITE_STATI
221f0 43 5d 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d  C], SQLite assum
22200 65 73 20 74 68 61 74 20 74 68 65 20 76 61 6c 75  es that the valu
22210 65 20 56 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  e V.**          
22220 69 73 20 68 65 6c 64 20 69 6e 20 73 74 61 74 69  is held in stati
22230 63 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  c unmanaged spac
22240 65 20 74 68 61 74 20 77 69 6c 6c 20 6e 6f 74 20  e that will not 
22250 63 68 61 6e 67 65 0a 2a 2a 20 20 20 20 20 20 20  change.**       
22260 20 20 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69     during the li
22270 66 65 74 69 6d 65 20 6f 66 20 74 68 65 20 62 69  fetime of the bi
22280 6e 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  nding..**.** {H1
22290 33 35 34 32 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3542} In calls t
222a0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
222b0 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  blob(S,N,V,L,D)]
222c0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
222d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
222e0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72  (S,N,V,L,D)], or
222f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
22300 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
22310 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68  6(S,N,V,L,D)] wh
22320 65 6e 20 44 20 69 73 20 74 68 65 20 73 70 65 63  en D is the spec
22330 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ial.**          
22340 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45  constant [SQLITE
22350 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
22360 20 72 6f 75 74 69 6e 65 20 6d 61 6b 65 73 20 61   routine makes a
22370 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 69  .**          pri
22380 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
22390 20 76 61 6c 75 65 20 56 20 62 65 66 6f 72 65 20   value V before 
223a0 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  it returns..**.*
223b0 2a 20 7b 48 31 33 35 34 35 7d 20 49 6e 20 63 61  * {H13545} In ca
223c0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
223d0 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
223e0 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
223f0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
22400 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
22410 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
22420 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
22430 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
22440 29 5d 20 77 68 65 6e 20 44 20 69 73 20 61 20 70  )] when D is a p
22450 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20  ointer to.**    
22460 20 20 20 20 20 20 61 20 66 75 6e 63 74 69 6f 6e        a function
22470 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  , SQLite invokes
22480 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 74   that function t
22490 6f 20 64 65 73 74 72 6f 79 20 74 68 65 0a 2a 2a  o destroy the.**
224a0 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
224b0 56 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  V after it has f
224c0 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
224d0 65 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a  e value V..**.**
224e0 20 7b 48 31 33 35 34 38 7d 20 49 6e 20 63 61 6c   {H13548} In cal
224f0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ls to [sqlite3_b
22500 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 53 2c 4e  ind_zeroblob(S,N
22510 2c 56 2c 4c 29 5d 20 74 68 65 20 76 61 6c 75 65  ,V,L)] the value
22520 20 62 6f 75 6e 64 0a 2a 2a 20 20 20 20 20 20 20   bound.**       
22530 20 20 20 69 73 20 61 20 42 4c 4f 42 20 6f 66 20     is a BLOB of 
22540 4c 20 62 79 74 65 73 2c 20 6f 72 20 61 20 7a 65  L bytes, or a ze
22550 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
22560 66 20 4c 20 69 73 20 6e 65 67 61 74 69 76 65 2e  f L is negative.
22570 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 35 31 7d 20  .**.** {H13551} 
22580 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
22590 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
225a0 53 2c 4e 2c 56 29 5d 20 74 68 65 20 56 20 61 72  S,N,V)] the V ar
225b0 67 75 6d 65 6e 74 20 6d 61 79 0a 2a 2a 20 20 20  gument may.**   
225c0 20 20 20 20 20 20 20 62 65 20 65 69 74 68 65 72         be either
225d0 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71   a [protected sq
225e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
225f0 65 63 74 20 6f 72 20 61 6e 0a 2a 2a 20 20 20 20  ect or an.**    
22600 20 20 20 20 20 20 5b 75 6e 70 72 6f 74 65 63 74        [unprotect
22610 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
22620 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74  ] object..*/.int
22630 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
22640 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
22650 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
22660 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
22670 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
22680 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
22690 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
226a0 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
226b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
226c0 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
226d0 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
226e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
226f0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
22700 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
22710 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
22720 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
22730 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
22740 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
22750 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
22760 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
22770 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
22780 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
22790 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
227a0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c  _bind_text16(sql
227b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
227c0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
227d0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
227e0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
227f0 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
22800 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
22810 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
22820 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
22830 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
22840 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
22850 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  nt, int n);../*.
22860 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
22870 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
22880 65 74 65 72 73 20 7b 48 31 33 36 30 30 7d 20 3c  eters {H13600} <
22890 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S70300>.**.** Th
228a0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
228b0 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
228c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
228d0 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
228e0 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
228f0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
22900 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
22910 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
22920 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
22930 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
22940 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
22950 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
22960 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
22970 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
22980 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
22990 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
229a0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
229b0 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
229c0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
229d0 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
229e0 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
229f0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
22a00 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
22a10 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
22a20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
22a30 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
22a40 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
22a50 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
22a60 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
22a70 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
22a80 20 74 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73   the ?NNN are us
22a90 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79  ed,.** there may
22aa0 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20   be gaps in the 
22ab0 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  list..**.** See 
22ac0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
22ad0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
22ae0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
22af0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
22b00 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
22b10 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
22b20 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
22b30 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ex()]..**.** INV
22b40 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
22b50 48 31 33 36 30 31 7d 20 54 68 65 20 5b 73 71 6c  H13601} The [sql
22b60 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
22b70 74 65 72 5f 63 6f 75 6e 74 28 53 29 5d 20 69 6e  ter_count(S)] in
22b80 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
22b90 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
22ba0 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66  largest index of
22bb0 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d 65 74   all SQL paramet
22bc0 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  ers in the.**   
22bd0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
22be0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 20 6f   statement] S, o
22bf0 72 20 30 20 69 66 20 53 20 63 6f 6e 74 61 69 6e  r 0 if S contain
22c00 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65 74  s no SQL paramet
22c10 65 72 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ers..*/.int sqli
22c20 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
22c30 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
22c40 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
22c50 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
22c60 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
22c70 65 72 20 7b 48 31 33 36 32 30 7d 20 3c 53 37 30  er {H13620} <S70
22c80 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  300>.**.** This 
22c90 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
22ca0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
22cb0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74   name of the n-t
22cc0 68 0a 2a 2a 20 5b 53 51 4c 20 70 61 72 61 6d 65  h.** [SQL parame
22cd0 74 65 72 5d 20 69 6e 20 61 20 5b 70 72 65 70 61  ter] in a [prepa
22ce0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
22cf0 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
22d00 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
22d10 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
22d20 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
22d30 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d  A".** have a nam
22d40 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  e which is the s
22d50 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20  tring "?NNN" or 
22d60 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
22d70 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65   or "$AAA".** re
22d80 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49  spectively..** I
22d90 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
22da0 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
22db0 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20  r "$" or "@" or 
22dc0 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "?".** is includ
22dd0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
22de0 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d  e name..** Param
22df0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
22e00 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
22e10 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
22e20 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
22e30 2a 20 61 6e 64 20 61 72 65 20 61 6c 73 6f 20 72  * and are also r
22e40 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 61  eferred to as "a
22e50 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
22e60 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ers"..**.** The 
22e70 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d  first host param
22e80 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
22e90 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
22ea0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75  *.** If the valu
22eb0 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e n is out of ra
22ec0 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d  nge or if the n-
22ed0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
22ee0 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
22ef0 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
22f00 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65  ed.  The returne
22f10 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61  d string is.** a
22f20 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65  lways in UTF-8 e
22f30 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
22f40 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
22f50 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69  ter was.** origi
22f60 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20  nally specified 
22f70 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
22f80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
22f90 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
22fa0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
22fb0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
22fc0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
22fd0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
22fe0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
22ff0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
23000 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
23010 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
23020 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
23030 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
23040 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
23050 33 36 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3621} The [sqlit
23060 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
23070 72 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74  r_name(S,N)] int
23080 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
23090 2a 20 20 20 20 20 20 20 20 20 20 61 20 55 54 46  *          a UTF
230a0 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
230b0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
230c0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e  SQL parameter in
230d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
230e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
230f0 6d 65 6e 74 5d 20 53 20 68 61 76 69 6e 67 20 69  ment] S having i
23100 6e 64 65 78 20 4e 2c 20 6f 72 0a 2a 2a 20 20 20  ndex N, or.**   
23110 20 20 20 20 20 20 20 4e 55 4c 4c 20 69 66 20 74         NULL if t
23120 68 65 72 65 20 69 73 20 6e 6f 20 53 51 4c 20 70  here is no SQL p
23130 61 72 61 6d 65 74 65 72 20 77 69 74 68 20 69 6e  arameter with in
23140 64 65 78 20 4e 20 6f 72 20 69 66 20 74 68 65 0a  dex N or if the.
23150 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61  **          para
23160 6d 65 74 65 72 20 77 69 74 68 20 69 6e 64 65 78  meter with index
23170 20 4e 20 69 73 20 61 6e 20 61 6e 6f 6e 79 6d 6f   N is an anonymo
23180 75 73 20 70 61 72 61 6d 65 74 65 72 20 22 3f 22  us parameter "?"
23190 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
231a0 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  *sqlite3_bind_pa
231b0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c  rameter_name(sql
231c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
231d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
231e0 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61  F: Index Of A Pa
231f0 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47  rameter With A G
23200 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31 33 36 34  iven Name {H1364
23210 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a  0} <S70300>.**.*
23220 2a 20 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64  * Return the ind
23230 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
23240 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
23250 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a 2a 20 69   name.  The.** i
23260 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
23270 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
23280 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
23290 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
232a0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
232b0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
232c0 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20 7a 65 72  _bind()].  A zer
232d0 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
232e0 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
232f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
23300 6e 64 2e 20 20 54 68 65 20 70 61 72 61 6d 65 74  nd.  The paramet
23310 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
23320 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
23330 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
23340 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
23350 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
23360 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
23370 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
23380 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
23390 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
233a0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
233b0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
233c0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
233d0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
233e0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
233f0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
23400 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
23410 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
23420 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
23430 36 34 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  641} The [sqlite
23440 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
23450 5f 69 6e 64 65 78 28 53 2c 4e 29 5d 20 69 6e 74  _index(S,N)] int
23460 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
23470 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 69  *          the i
23480 6e 64 65 78 20 6f 66 20 53 51 4c 20 70 61 72 61  ndex of SQL para
23490 6d 65 74 65 72 20 69 6e 20 74 68 65 20 5b 70 72  meter in the [pr
234a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
234b0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 20  ].**          S 
234c0 77 68 6f 73 65 20 6e 61 6d 65 20 6d 61 74 63 68  whose name match
234d0 65 73 20 74 68 65 20 55 54 46 2d 38 20 73 74 72  es the UTF-8 str
234e0 69 6e 67 20 4e 2c 20 6f 72 20 30 20 69 66 20 74  ing N, or 0 if t
234f0 68 65 72 65 20 69 73 0a 2a 2a 20 20 20 20 20 20  here is.**      
23500 20 20 20 20 6e 6f 20 6d 61 74 63 68 2e 0a 2a 2f      no match..*/
23510 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
23520 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
23530 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
23540 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
23550 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
23560 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
23570 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
23580 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
23590 20 7b 48 31 33 36 36 30 7d 20 3c 53 37 30 33 30   {H13660} <S7030
235a0 30 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72  0>.**.** Contrar
235b0 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
235c0 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
235d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
235e0 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20  es not reset.** 
235f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
23600 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
23610 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  s] on a [prepare
23620 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
23630 20 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e   Use this routin
23640 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68  e to reset all h
23650 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
23660 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e  o NULL..**.** IN
23670 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
23680 7b 48 31 33 36 36 31 7d 20 54 68 65 20 5b 73 71  {H13661} The [sq
23690 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
236a0 69 6e 67 73 28 53 29 5d 20 69 6e 74 65 72 66 61  ings(S)] interfa
236b0 63 65 20 72 65 73 65 74 73 20 61 6c 6c 20 53 51  ce resets all SQ
236c0 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  L.**          pa
236d0 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 73  rameter bindings
236e0 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
236f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 62  d statement] S b
23700 61 63 6b 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a  ack to NULL..*/.
23710 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
23720 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
23730 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
23740 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
23750 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
23760 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48   A Result Set {H
23770 31 33 37 31 30 7d 20 3c 53 31 30 37 30 30 3e 0a  13710} <S10700>.
23780 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65  **.** Return the
23790 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
237a0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
237b0 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79   set returned by
237c0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
237d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 54 68  d statement]. Th
237e0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
237f0 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73  ns 0 if pStmt is
23800 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65   an SQL.** state
23810 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
23820 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
23830 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b  for example an [
23840 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20  UPDATE])..**.** 
23850 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
23860 2a 20 7b 48 31 33 37 31 31 7d 20 54 68 65 20 5b  * {H13711} The [
23870 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
23880 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66 61  ount(S)] interfa
23890 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
238a0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20  umber of.**     
238b0 20 20 20 20 20 63 6f 6c 75 6d 6e 73 20 69 6e 20       columns in 
238c0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 67  the result set g
238d0 65 6e 65 72 61 74 65 64 20 62 79 20 74 68 65 20  enerated by the 
238e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
238f0 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20 20 20  ent] S,.**      
23900 20 20 20 20 6f 72 20 30 20 69 66 20 53 20 64 6f      or 0 if S do
23910 65 73 20 6e 6f 74 20 67 65 6e 65 72 61 74 65 20  es not generate 
23920 61 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a 2f  a result set..*/
23930 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
23940 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
23950 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
23960 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23970 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
23980 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48   A Result Set {H
23990 31 33 37 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a  13720} <S10700>.
239a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
239b0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
239c0 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
239d0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
239e0 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
239f0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
23a00 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
23a10 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
23a20 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
23a30 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
23a40 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
23a50 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
23a60 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
23a70 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
23a80 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
23a90 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
23aa0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
23ab0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
23ac0 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72 73  tring.  The firs
23ad0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
23ae0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
23af0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
23b00 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
23b10 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
23b20 74 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  t. The second pa
23b30 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
23b40 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
23b50 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63    The leftmost c
23b60 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
23b70 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74  0..**.** The ret
23b80 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
23b90 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
23ba0 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
23bb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23bc0 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
23bd0 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
23be0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
23bf0 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
23c00 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
23c10 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
23c20 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
23c30 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65  _name16() on the
23c40 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
23c50 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d  .** If sqlite3_m
23c60 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
23c70 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
23c80 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
23c90 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
23ca0 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
23cb0 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
23cc0 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
23cd0 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
23ce0 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
23cf0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  ed..**.** The na
23d00 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  me of a result c
23d10 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c  olumn is the val
23d20 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63  ue of the "AS" c
23d30 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61  lause for.** tha
23d40 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65  t column, if the
23d50 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75  re is an AS clau
23d60 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  se.  If there is
23d70 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a   no AS clause.**
23d80 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f   then the name o
23d90 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
23da0 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
23db0 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a  may change from.
23dc0 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f  ** one release o
23dd0 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  f SQLite to the 
23de0 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  next..**.** INVA
23df0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
23e00 31 33 37 32 31 7d 20 41 20 73 75 63 63 65 73 73  13721} A success
23e10 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
23e20 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
23e30 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d  olumn_name(S,N)]
23e40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
23e50 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
23e60 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
23e70 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72 65  th column (where
23e80 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20   0 is.**        
23e90 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20 63    the leftmost c
23ea0 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 20 72  olumn) for the r
23eb0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65  esult set of the
23ec0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
23ed0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23ee0 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d 74 65  ] S as a zero-te
23ef0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
23f00 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  tring..**.** {H1
23f10 33 37 32 33 7d 20 41 20 73 75 63 63 65 73 73 66  3723} A successf
23f20 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ul invocation of
23f30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
23f40 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  lumn_name16(S,N)
23f50 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
23f60 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
23f70 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
23f80 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 77 68 65 72  Nth column (wher
23f90 65 20 30 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  e 0 is.**       
23fa0 20 20 20 74 68 65 20 6c 65 66 74 6d 6f 73 74 20     the leftmost 
23fb0 63 6f 6c 75 6d 6e 29 20 66 6f 72 20 74 68 65 20  column) for the 
23fc0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
23fd0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
23fe0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23ff0 74 5d 20 53 20 61 73 20 61 20 7a 65 72 6f 2d 74  t] S as a zero-t
24000 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36  erminated UTF-16
24010 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20   string.**      
24020 20 20 20 20 69 6e 20 74 68 65 20 6e 61 74 69 76      in the nativ
24030 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
24040 0a 2a 2a 20 7b 48 31 33 37 32 34 7d 20 54 68 65  .** {H13724} The
24050 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24060 5f 6e 61 6d 65 28 29 5d 20 61 6e 64 20 5b 73 71  _name()] and [sq
24070 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
24080 65 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  e16()].**       
24090 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65     interfaces re
240a0 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  turn a NULL poin
240b0 74 65 72 20 69 66 20 74 68 65 79 20 61 72 65 20  ter if they are 
240c0 75 6e 61 62 6c 65 20 74 6f 0a 2a 2a 20 20 20 20  unable to.**    
240d0 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 65 20 6d        allocate m
240e0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
240f0 65 69 72 20 6e 6f 72 6d 61 6c 20 72 65 74 75 72  eir normal retur
24100 6e 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a  n strings..**.**
24110 20 7b 48 31 33 37 32 35 7d 20 49 66 20 74 68 65   {H13725} If the
24120 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   N parameter to 
24130 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
24140 6e 61 6d 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a  name(S,N)] or.**
24150 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
24160 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
24170 28 53 2c 4e 29 5d 20 69 73 20 6f 75 74 20 6f 66  (S,N)] is out of
24180 20 72 61 6e 67 65 2c 20 74 68 65 6e 20 74 68 65   range, then the
24190 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
241a0 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 61  erfaces return a
241b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
241c0 2a 0a 2a 2a 20 7b 48 31 33 37 32 36 7d 20 54 68  *.** {H13726} Th
241d0 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
241e0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
241f0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d  olumn_name(S,N)]
24200 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
24210 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24220 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 61 72  _name16(S,N)] ar
24230 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  e valid until th
24240 65 20 6e 65 78 74 0a 2a 2a 20 20 20 20 20 20 20  e next.**       
24250 20 20 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65     call to eithe
24260 72 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 74  r routine with t
24270 68 65 20 73 61 6d 65 20 53 20 61 6e 64 20 4e 20  he same S and N 
24280 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20  parameters.**   
24290 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c 20         or until 
242a0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
242b0 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  e(S)] is called.
242c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 37 7d 20  .**.** {H13727} 
242d0 57 68 65 6e 20 61 20 72 65 73 75 6c 74 20 63 6f  When a result co
242e0 6c 75 6d 6e 20 6f 66 20 61 20 5b 53 45 4c 45 43  lumn of a [SELEC
242f0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6e  T] statement con
24300 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  tains.**        
24310 20 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2c 20    an AS clause, 
24320 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 61 74  the name of that
24330 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 69   column is the i
24340 64 65 6e 74 69 66 69 65 72 0a 2a 2a 20 20 20 20  dentifier.**    
24350 20 20 20 20 20 20 74 6f 20 74 68 65 20 72 69 67        to the rig
24360 68 74 20 6f 66 20 74 68 65 20 41 53 20 6b 65 79  ht of the AS key
24370 77 6f 72 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  word..*/.const c
24380 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
24390 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
243a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
243b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
243c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
243d0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
243e0 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
243f0 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
24400 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
24410 65 72 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37  ery Result {H137
24420 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a  40} <S10700>.**.
24430 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
24440 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e  s provide a mean
24450 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 77  s to determine w
24460 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68  hat column of wh
24470 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77  at.** table in w
24480 68 69 63 68 20 64 61 74 61 62 61 73 65 20 61 20  hich database a 
24490 72 65 73 75 6c 74 20 6f 66 20 61 20 5b 53 45 4c  result of a [SEL
244a0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 63  ECT] statement c
244b0 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68  omes from..** Th
244c0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
244d0 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20  tabase or table 
244e0 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65  or column can be
244f0 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
24500 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f  either a UTF-8 o
24510 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  r UTF-16 string.
24520 20 20 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f    The _database_
24530 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
24540 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
24550 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
24560 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
24570 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
24580 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
24590 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
245a0 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
245b0 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65   name..** The re
245c0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
245d0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
245e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
245f0 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
24600 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
24610 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
24620 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
24630 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
24640 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
24650 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
24660 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
24670 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73 20 72 65  .** The names re
24680 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
24690 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
246a0 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
246b0 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
246c0 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
246d0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
246e0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
246f0 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20  following calls 
24700 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
24710 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68  tatement]..** Th
24720 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
24730 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
24740 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 63   about the Nth c
24750 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
24760 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
24770 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
24780 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
24790 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  on argument..**.
247a0 2a 2a 20 49 66 20 74 68 65 20 4e 74 68 20 63 6f  ** If the Nth co
247b0 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
247c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
247d0 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
247e0 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
247f0 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
24800 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
24810 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
24820 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
24830 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20 72 6f 75  NULL.  These rou
24840 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
24850 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
24860 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
24870 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
24880 72 73 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20  rs.  Otherwise, 
24890 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
248a0 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61  name of the atta
248b0 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74  ched database, t
248c0 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63 6f 6c 75  able.** and colu
248d0 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65  mn that query re
248e0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20  sult column was 
248f0 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a  extracted from..
24900 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68 20 61 6c  **.** As with al
24910 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
24920 50 49 73 2c 20 74 68 6f 73 65 20 70 6f 73 74 66  PIs, those postf
24930 69 78 65 64 20 77 69 74 68 20 22 31 36 22 20 72  ixed with "16" r
24940 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
24950 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 2c  encoded strings,
24960 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
24970 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
24980 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  8. {END}.**.** T
24990 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
249a0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
249b0 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
249c0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
249d0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
249e0 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
249f0 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
24a00 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  sor symbol defin
24a10 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35  ed..**.** {A1375
24a20 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  1}.** If two or 
24a30 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
24a40 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
24a50 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
24a60 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
24a70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
24a80 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
24a90 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
24aa0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
24ab0 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
24ac0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ined..**.** INVA
24ad0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
24ae0 31 33 37 34 31 7d 20 54 68 65 20 5b 73 71 6c 69  13741} The [sqli
24af0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
24b00 61 73 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69  ase_name(S,N)] i
24b10 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24b20 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
24b30 20 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65      the UTF-8 ze
24b40 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61  ro-terminated na
24b50 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
24b60 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  se from which th
24b70 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
24b80 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
24b90 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  of the [prepared
24ba0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73   statement] S is
24bb0 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20   extracted,.**  
24bc0 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20          or NULL 
24bd0 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
24be0 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65  n of S is a gene
24bf0 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  ral expression.*
24c00 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66  *          or if
24c10 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
24c20 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74  ate memory to st
24c30 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
24c40 0a 2a 2a 20 7b 48 31 33 37 34 32 7d 20 54 68 65  .** {H13742} The
24c50 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24c60 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
24c70 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
24c80 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a   returns either.
24c90 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
24ca0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
24cb0 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65  te order zero-te
24cc0 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
24cd0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
24ce0 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 77            from w
24cf0 68 69 63 68 20 74 68 65 20 4e 74 68 20 72 65 73  hich the Nth res
24d00 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ult column of th
24d10 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
24d20 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a 20 20  ement] S is.**  
24d30 20 20 20 20 20 20 20 20 65 78 74 72 61 63 74 65          extracte
24d40 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
24d50 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
24d60 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65  S is a general e
24d70 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20  xpression.**    
24d80 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62        or if unab
24d90 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
24da0 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74  emory to store t
24db0 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b  he name..**.** {
24dc0 48 31 33 37 34 33 7d 20 54 68 65 20 5b 73 71 6c  H13743} The [sql
24dd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
24de0 65 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74  e_name(S,N)] int
24df0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
24e00 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
24e10 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72 6f    the UTF-8 zero
24e20 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65  -terminated name
24e30 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 66 72   of the table fr
24e40 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  om which the.** 
24e50 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73           Nth res
24e60 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ult column of th
24e70 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
24e80 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72  ement] S is extr
24e90 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20  acted,.**       
24ea0 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68     or NULL if th
24eb0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
24ec0 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65  S is a general e
24ed0 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20  xpression.**    
24ee0 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62        or if unab
24ef0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
24f00 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74  emory to store t
24f10 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b  he name..**.** {
24f20 48 31 33 37 34 34 7d 20 54 68 65 20 5b 73 71 6c  H13744} The [sql
24f30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
24f40 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69  e_name16(S,N)] i
24f50 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24f60 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
24f70 20 20 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e      the UTF-16 n
24f80 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
24f90 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
24fa0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62   name of the tab
24fb0 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  le.**          f
24fc0 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74  rom which the Nt
24fd0 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
24fe0 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  of the [prepared
24ff0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73   statement] S is
25000 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 74  .**          ext
25010 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20  racted, or NULL 
25020 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
25030 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65  n of S is a gene
25040 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  ral expression.*
25050 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69 66  *          or if
25060 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
25070 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74  ate memory to st
25080 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a  ore the name..**
25090 0a 2a 2a 20 7b 48 31 33 37 34 35 7d 20 54 68 65  .** {H13745} The
250a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
250b0 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 53 2c 4e  _origin_name(S,N
250c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
250d0 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
250e0 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
250f0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
25100 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61  d name of the ta
25110 62 6c 65 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20  ble column from 
25120 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20  which the.**    
25130 20 20 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74        Nth result
25140 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b   column of the [
25150 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25160 6e 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74  nt] S is extract
25170 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ed,.**          
25180 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e  or NULL if the N
25190 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69  th column of S i
251a0 73 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72  s a general expr
251b0 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  ession.**       
251c0 20 20 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20     or if unable 
251d0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
251e0 72 79 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20  ry to store the 
251f0 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  name..**.** {H13
25200 37 34 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  746} The [sqlite
25210 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
25220 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74  name16(S,N)] int
25230 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
25240 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
25250 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74    the UTF-16 nat
25260 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a  ive byte order z
25270 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
25280 61 6d 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ame of the table
25290 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c  .**          col
252a0 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68 20 74  umn from which t
252b0 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
252c0 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 20  lumn of the.**  
252d0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
252e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
252f0 73 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72 20  s extracted, or 
25300 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20  NULL if the Nth 
25310 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20  column.**       
25320 20 20 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e     of S is a gen
25330 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 20  eral expression 
25340 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20  or if unable to 
25350 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 0a  allocate memory.
25360 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 73  **          to s
25370 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
25380 2a 0a 2a 2a 20 7b 48 31 33 37 34 38 7d 20 54 68  *.** {H13748} Th
25390 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 20  e return values 
253a0 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20  from.**         
253b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
253c0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
253d0 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
253e0 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
253f0 20 20 20 20 20 20 20 20 20 61 72 65 20 76 61 6c           are val
25400 69 64 20 66 6f 72 20 74 68 65 20 6c 69 66 65 74  id for the lifet
25410 69 6d 65 20 6f 66 20 74 68 65 20 5b 70 72 65 70  ime of the [prep
25420 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
25430 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 75  **          or u
25440 6e 74 69 6c 20 74 68 65 20 65 6e 63 6f 64 69 6e  ntil the encodin
25450 67 20 69 73 20 63 68 61 6e 67 65 64 20 62 79 20  g is changed by 
25460 61 6e 6f 74 68 65 72 20 6d 65 74 61 64 61 74 61  another metadata
25470 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
25480 65 72 66 61 63 65 20 63 61 6c 6c 20 66 6f 72 20  erface call for 
25490 74 68 65 20 73 61 6d 65 20 70 72 65 70 61 72 65  the same prepare
254a0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
254b0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 41 53  column..**.** AS
254c0 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
254d0 20 7b 41 31 33 37 35 31 7d 20 49 66 20 74 77 6f   {A13751} If two
254e0 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
254f0 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
25500 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
25510 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
25520 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
25530 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
25540 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20  terfaces].**    
25550 20 20 20 20 20 20 66 6f 72 20 74 68 65 20 73 61        for the sa
25560 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
25570 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
25580 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 20 20 20  lt column.**    
25590 20 20 20 20 20 20 61 74 20 74 68 65 20 73 61 6d        at the sam
255a0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
255b0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
255c0 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
255d0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
255e0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
255f0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
25600 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
25610 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
25620 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
25630 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
25640 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
25650 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
25660 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
25670 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
25680 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
25690 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
256a0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
256b0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
256c0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
256d0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
256e0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
256f0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
25700 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
25710 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
25720 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
25730 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
25740 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
25750 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
25760 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37 36 30  y Result {H13760
25770 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10700>.**.**
25780 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
25790 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
257a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
257b0 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
257c0 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
257d0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
257e0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
257f0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
25800 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
25810 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
25820 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
25830 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
25840 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
25850 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
25860 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
25870 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
25880 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  n is returned.  
25890 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
258a0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
258b0 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
258c0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
258d0 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
258e0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
258f0 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74  rned..** The ret
25900 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
25910 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
25920 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  oded. {END}.**.*
25930 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  * For example, g
25940 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
25950 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
25960 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
25970 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
25980 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
25990 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
259a0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
259b0 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
259c0 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
259d0 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
259e0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
259f0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
25a00 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
25a10 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
25a20 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
25a30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
25a40 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
25a50 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
25a60 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  0)..**.** SQLite
25a70 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
25a80 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
25a90 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
25aa0 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
25ab0 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
25ac0 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
25ad0 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
25ae0 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
25af0 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
25b00 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
25b10 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
25b20 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
25b30 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
25b40 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
25b50 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
25b60 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20  tatic.  Type.** 
25b70 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
25b80 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
25b90 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
25ba0 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
25bb0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
25bc0 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a  ose values..**.*
25bd0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
25be0 0a 2a 2a 20 7b 48 31 33 37 36 31 7d 20 20 41 20  .** {H13761}  A 
25bf0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
25c00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  to [sqlite3_colu
25c10 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e 29  mn_decltype(S,N)
25c20 5d 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20  ] returns a.**  
25c30 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d 74 65           zero-te
25c40 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
25c50 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
25c60 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64 61   the declared da
25c70 74 61 74 79 70 65 0a 2a 2a 20 20 20 20 20 20 20  tatype.**       
25c80 20 20 20 20 6f 66 20 74 68 65 20 74 61 62 6c 65      of the table
25c90 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70   column that app
25ca0 65 61 72 73 20 61 73 20 74 68 65 20 4e 74 68 20  ears as the Nth 
25cb0 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65 64  column (numbered
25cc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 66 72  .**           fr
25cd0 6f 6d 20 30 29 20 6f 66 20 74 68 65 20 72 65 73  om 0) of the res
25ce0 75 6c 74 20 73 65 74 20 74 6f 20 74 68 65 20 5b  ult set to the [
25cf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25d00 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  nt] S..**.** {H1
25d10 33 37 36 32 7d 20 20 41 20 73 75 63 63 65 73 73  3762}  A success
25d20 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
25d30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
25d40 74 79 70 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20  type16(S,N)].** 
25d50 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
25d60 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
25d70 74 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76  ted UTF-16 nativ
25d80 65 20 62 79 74 65 20 6f 72 64 65 72 20 73 74 72  e byte order str
25d90 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
25da0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
25db0 64 65 63 6c 61 72 65 64 20 64 61 74 61 74 79 70  declared datatyp
25dc0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
25dd0 6f 6c 75 6d 6e 20 74 68 61 74 20 61 70 70 65 61  olumn that appea
25de0 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  rs.**           
25df0 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  as the Nth colum
25e00 6e 20 28 6e 75 6d 62 65 72 65 64 20 66 72 6f 6d  n (numbered from
25e10 20 30 29 20 6f 66 20 74 68 65 20 72 65 73 75 6c   0) of the resul
25e20 74 20 73 65 74 20 74 6f 20 74 68 65 0a 2a 2a 20  t set to the.** 
25e30 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
25e40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
25e50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 33 7d  ..**.** {H13763}
25e60 20 20 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74    If N is less t
25e70 68 61 6e 20 30 20 6f 72 20 4e 20 69 73 20 67 72  han 0 or N is gr
25e80 65 61 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71  eater than or eq
25e90 75 61 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ual to.**       
25ea0 20 20 20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f      the number o
25eb0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
25ec0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25ed0 6d 65 6e 74 5d 20 53 2c 0a 2a 2a 20 20 20 20 20  ment] S,.**     
25ee0 20 20 20 20 20 20 6f 72 20 69 66 20 74 68 65 20        or if the 
25ef0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20  Nth column of S 
25f00 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
25f10 20 6f 72 20 73 75 62 71 75 65 72 79 20 72 61 74   or subquery rat
25f20 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
25f30 20 74 68 61 6e 20 61 20 74 61 62 6c 65 20 63 6f   than a table co
25f40 6c 75 6d 6e 2c 20 6f 72 20 69 66 20 61 20 6d 65  lumn, or if a me
25f50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
25f60 66 61 69 6c 75 72 65 0a 2a 2a 20 20 20 20 20 20  failure.**      
25f70 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72 69       occurs duri
25f80 6e 67 20 65 6e 63 6f 64 69 6e 67 20 63 6f 6e 76  ng encoding conv
25f90 65 72 73 69 6f 6e 73 2c 20 74 68 65 6e 0a 2a 2a  ersions, then.**
25fa0 20 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 73             calls
25fb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
25fc0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 53 2c 4e  umn_decltype(S,N
25fd0 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  )] or.**        
25fe0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
25ff0 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c  mn_decltype16(S,
26000 4e 29 5d 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e  N)] return NULL.
26010 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
26020 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
26030 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
26040 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
26050 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
26060 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
26070 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
26080 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
26090 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
260a0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
260b0 20 7b 48 31 33 32 30 30 7d 20 3c 53 31 30 30 30   {H13200} <S1000
260c0 30 3e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  0>.**.** After a
260d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
260e0 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
260f0 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69  repared using ei
26100 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
26110 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
26120 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
26130 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  re16_v2()] or on
26140 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
26150 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
26160 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
26170 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
26180 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
26190 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
261a0 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
261b0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
261c0 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
261d0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
261e0 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
261f0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
26200 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
26210 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
26220 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
26230 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
26240 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
26250 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
26260 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
26270 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
26280 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
26290 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
262a0 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
262b0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
262c0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
262d0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
262e0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
262f0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
26300 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
26310 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
26320 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
26330 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
26340 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
26350 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
26360 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
26370 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  rted..**.** In t
26380 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
26390 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
263a0 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
263b0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
263c0 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
263d0 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
263e0 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
263f0 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
26400 49 53 55 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20  ISUSE]..** With 
26410 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
26420 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
26430 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
26440 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
26450 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
26460 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
26470 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
26480 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
26490 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
264a0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
264b0 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
264c0 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
264d0 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
264e0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
264f0 6f 62 2e 20 20 49 66 20 74 68 65 20 73 74 61 74  ob.  If the stat
26500 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
26510 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
26520 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
26530 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
26540 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
26550 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
26560 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
26570 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
26580 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
26590 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
265a0 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  a.** explicit tr
265b0 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
265c0 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
265d0 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
265e0 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
265f0 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b  tinuing..**.** [
26600 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
26610 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
26620 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
26630 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
26640 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
26650 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
26660 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
26670 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
26680 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
26690 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
266a0 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
266b0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
266c0 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
266d0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
266e0 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
266f0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  state..**.** If 
26700 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
26710 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
26720 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
26730 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
26740 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
26750 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
26760 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
26770 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
26780 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
26790 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
267a0 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
267b0 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
267c0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
267d0 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
267e0 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
267f0 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
26800 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
26810 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
26820 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
26830 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20  R] means that a 
26840 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28  run-time error (
26850 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72  such as a constr
26860 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f  aint.** violatio
26870 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e  n) has occurred.
26880 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
26890 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
268a0 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a  alled again on.*
268b0 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69  * the VM. More i
268c0 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62  nformation may b
268d0 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69  e found by calli
268e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ng [sqlite3_errm
268f0 73 67 28 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74  sg()]..** With t
26900 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
26910 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63  ace, a more spec
26920 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
26930 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (for example,.**
26940 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
26950 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  PT], [SQLITE_SCH
26960 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EMA], [SQLITE_CO
26970 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66  RRUPT], and so f
26980 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20  orth).** can be 
26990 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c  obtained by call
269a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
269b0 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20  et()] on the.** 
269c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
269d0 65 6e 74 5d 2e 20 20 49 6e 20 74 68 65 20 22 76  ent].  In the "v
269e0 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a  2" interface,.**
269f0 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
26a00 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  ic error code is
26a10 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
26a20 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ly by sqlite3_st
26a30 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  ep()..**.** [SQL
26a40 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e  ITE_MISUSE] mean
26a50 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20  s that the this 
26a60 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c  routine was call
26a70 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65  ed inappropriate
26a80 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69  ly..** Perhaps i
26a90 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20  t was called on 
26aa0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
26ab0 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a  ement] that has.
26ac0 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  ** already been 
26ad0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
26ae0 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f  e | finalized] o
26af0 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61  r on one that ha
26b00 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  d.** previously 
26b10 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
26b20 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49  _ERROR] or [SQLI
26b30 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74  TE_DONE].  Or it
26b40 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65   could.** be the
26b50 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73   case that the s
26b60 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
26b70 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67  nection is being
26b80 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a   used by two or.
26b90 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  ** more threads 
26ba0 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65  at the same mome
26bb0 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  nt in time..**.*
26bc0 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72  * <b>Goofy Inter
26bd0 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20  face Alert:</b> 
26be0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
26bf0 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c  terface, the sql
26c00 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41  ite3_step().** A
26c10 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  PI always return
26c20 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f  s a generic erro
26c30 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f  r code, [SQLITE_
26c40 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e  ERROR], followin
26c50 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f  g any.** error o
26c60 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
26c70 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c  E_BUSY] and [SQL
26c80 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f  ITE_MISUSE].  Yo
26c90 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b  u must call.** [
26ca0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
26cb0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
26cc0 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65  alize()] in orde
26cd0 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66  r to find one of
26ce0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
26cf0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74   [error codes] t
26d00 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72  hat better descr
26d10 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a  ibes the error..
26d20 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ** We admit that
26d30 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79   this is a goofy
26d40 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72   design.  The pr
26d50 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66  oblem has been f
26d60 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65  ixed.** with the
26d70 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e   "v2" interface.
26d80 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65    If you prepare
26d90 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c   all of your SQL
26da0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75   statements.** u
26db0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
26dc0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
26dd0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
26de0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69  repare16_v2()] i
26df0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65  nstead.** of the
26e00 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
26e10 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
26e20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26e30 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  16()] interfaces
26e40 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f  ,.** then the mo
26e50 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  re specific [err
26e60 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65  or codes] are re
26e70 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a  turned directly.
26e80 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ** by sqlite3_st
26e90 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f  ep().  The use o
26ea0 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  f the "v2" inter
26eb0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
26ec0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ded..**.** INVAR
26ed0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
26ee0 33 32 30 32 7d 20 20 49 66 20 74 68 65 20 5b 70  3202}  If the [p
26ef0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26f00 74 5d 20 53 20 69 73 20 72 65 61 64 79 20 74 6f  t] S is ready to
26f10 20 62 65 20 72 75 6e 2c 20 74 68 65 6e 0a 2a 2a   be run, then.**
26f20 20 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69             [sqli
26f30 74 65 33 5f 73 74 65 70 28 53 29 5d 20 61 64 76  te3_step(S)] adv
26f40 61 6e 63 65 73 20 74 68 61 74 20 70 72 65 70 61  ances that prepa
26f50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 6e  red statement un
26f60 74 69 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  til.**          
26f70 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 72 20 75   completion or u
26f80 6e 74 69 6c 20 69 74 20 69 73 20 72 65 61 64 79  ntil it is ready
26f90 20 74 6f 20 72 65 74 75 72 6e 20 61 6e 6f 74 68   to return anoth
26fa0 65 72 20 72 6f 77 20 6f 66 20 74 68 65 0a 2a 2a  er row of the.**
26fb0 20 20 20 20 20 20 20 20 20 20 20 72 65 73 75 6c             resul
26fc0 74 20 73 65 74 2c 20 6f 72 20 75 6e 74 69 6c 20  t set, or until 
26fd0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  an [sqlite3_inte
26fe0 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70  rrupt | interrup
26ff0 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  t].**           
27000 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  or a run-time er
27010 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
27020 2a 20 7b 48 31 35 33 30 34 7d 20 20 57 68 65 6e  * {H15304}  When
27030 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
27040 74 65 33 5f 73 74 65 70 28 53 29 5d 20 63 61 75  te3_step(S)] cau
27050 73 65 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ses the [prepare
27060 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
27070 20 20 20 20 20 20 20 20 20 20 53 20 74 6f 20 72            S to r
27080 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  un to completion
27090 2c 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72  , the function r
270a0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
270b0 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ONE]..**.** {H15
270c0 33 30 36 7d 20 20 57 68 65 6e 20 61 20 63 61 6c  306}  When a cal
270d0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
270e0 65 70 28 53 29 5d 20 73 74 6f 70 73 20 62 65 63  ep(S)] stops bec
270f0 61 75 73 65 20 69 74 20 69 73 20 72 65 61 64 79  ause it is ready
27100 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
27110 20 72 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 20   return another 
27120 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
27130 74 20 73 65 74 2c 20 69 74 20 72 65 74 75 72 6e  t set, it return
27140 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2e 0a  s [SQLITE_ROW]..
27150 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 38 7d 20 20  **.** {H15308}  
27160 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  If a call to [sq
27170 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 65  lite3_step(S)] e
27180 6e 63 6f 75 6e 74 65 72 73 20 61 6e 0a 2a 2a 20  ncounters an.** 
27190 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
271a0 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69  e3_interrupt | i
271b0 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20 72  nterrupt] or a r
271c0 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 2c 0a 2a  un-time error,.*
271d0 2a 20 20 20 20 20 20 20 20 20 20 20 69 74 20 72  *           it r
271e0 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
271f0 72 69 61 74 65 20 65 72 72 6f 72 20 63 6f 64 65  riate error code
27200 20 74 68 61 74 20 69 73 20 6e 6f 74 20 6f 6e 65   that is not one
27210 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
27220 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 5b 53   [SQLITE_OK], [S
27230 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 6f 72 20 5b  QLITE_ROW], or [
27240 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a  SQLITE_DONE]..**
27250 0a 2a 2a 20 7b 48 31 35 33 31 30 7d 20 20 49 66  .** {H15310}  If
27260 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74   an [sqlite3_int
27270 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72 75  errupt | interru
27280 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69 6d  pt] or a run-tim
27290 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20 20  e error.**      
272a0 20 20 20 20 20 6f 63 63 75 72 73 20 64 75 72 69       occurs duri
272b0 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
272c0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 0a 2a  lite3_step(S)].*
272d0 2a 20 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  *           for 
272e0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
272f0 65 6d 65 6e 74 5d 20 53 20 63 72 65 61 74 65 64  ement] S created
27300 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
27310 20 20 20 20 6c 65 67 61 63 79 20 69 6e 74 65 72      legacy inter
27320 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
27330 72 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20  repare()] or.** 
27340 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
27350 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
27360 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   then the functi
27370 6f 6e 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  on returns eithe
27380 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b  r.**           [
27390 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 5b  SQLITE_ERROR], [
273a0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 6f 72  SQLITE_BUSY], or
273b0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
273c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
273d0 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
273e0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
273f0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
27400 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
27410 73 75 6c 74 20 73 65 74 20 7b 48 31 33 37 37 30  sult set {H13770
27420 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10700>.**.**
27430 20 52 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   Returns the num
27440 62 65 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e  ber of values in
27450 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
27460 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
27470 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  et..**.** INVARI
27480 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ANTS:.**.** {H13
27490 37 37 31 7d 20 20 41 66 74 65 72 20 61 20 63 61  771}  After a ca
274a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
274b0 74 65 70 28 53 29 5d 20 74 68 61 74 20 72 65 74  tep(S)] that ret
274c0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 4f 57  urns [SQLITE_ROW
274d0 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ],.**           
274e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  the [sqlite3_dat
274f0 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74  a_count(S)] rout
27500 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ine will return 
27510 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 0a 2a  the same value.*
27520 2a 20 20 20 20 20 20 20 20 20 20 20 61 73 20 74  *           as t
27530 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
27540 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 66 75 6e  mn_count(S)] fun
27550 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ction..**.** {H1
27560 33 37 37 32 7d 20 20 41 66 74 65 72 20 5b 73 71  3772}  After [sq
27570 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
27580 61 73 20 72 65 74 75 72 6e 65 64 20 61 6e 79 20  as returned any 
27590 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
275a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53  .**           [S
275b0 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 62 65  QLITE_ROW] or be
275c0 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  fore [sqlite3_st
275d0 65 70 28 53 29 5d 20 68 61 73 20 62 65 65 6e 20  ep(S)] has been 
275e0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 0a 2a 2a  called on the.**
275f0 20 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70             [prep
27600 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
27610 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 74 69  for the first ti
27620 6d 65 20 73 69 6e 63 65 20 69 74 20 77 61 73 0a  me since it was.
27630 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73 71  **           [sq
27640 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
27650 70 72 65 70 61 72 65 64 5d 20 6f 72 20 5b 73 71  prepared] or [sq
27660 6c 69 74 65 33 5f 72 65 73 65 74 20 7c 20 72 65  lite3_reset | re
27670 73 65 74 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  set],.**        
27680 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f     the [sqlite3_
27690 64 61 74 61 5f 63 6f 75 6e 74 28 53 29 5d 20 72  data_count(S)] r
276a0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a  outine returns z
276b0 65 72 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ero..*/.int sqli
276c0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
276d0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
276e0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
276f0 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
27700 6c 20 44 61 74 61 74 79 70 65 73 20 7b 48 31 30  l Datatypes {H10
27710 32 36 35 7d 20 3c 53 31 30 31 31 30 3e 3c 53 31  265} <S10110><S1
27720 30 31 32 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0120>.** KEYWORD
27730 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
27740 2a 0a 2a 2a 20 7b 48 31 30 32 36 36 7d 20 45 76  *.** {H10266} Ev
27750 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
27760 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
27770 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
27780 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
27790 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
277a0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
277b0 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
277c0 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
277d0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
277e0 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
277f0 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
27800 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20  > NULL.** </ul> 
27810 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  {END}.**.** Thes
27820 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
27830 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
27840 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
27850 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
27860 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
27870 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
27880 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
27890 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
278a0 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
278b0 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
278c0 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
278d0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
278e0 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
278f0 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
27900 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
27910 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
27920 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
27930 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
27940 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
27950 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
27960 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
27970 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
27980 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
27990 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
279a0 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
279b0 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
279c0 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
279d0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
279e0 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
279f0 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
27a00 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
27a10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
27a20 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
27a30 6d 20 41 20 51 75 65 72 79 20 7b 48 31 33 38 30  m A Query {H1380
27a40 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b  0} <S10700>.** K
27a50 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
27a60 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
27a70 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s}.**.** These r
27a80 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
27a90 20 22 72 65 73 75 6c 74 20 73 65 74 20 71 75 65   "result set que
27aa0 72 79 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ry" interface..*
27ab0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
27ac0 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
27ad0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
27ae0 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
27af0 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
27b00 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
27b10 75 65 72 79 2e 20 20 49 6e 20 65 76 65 72 79 20  uery.  In every 
27b20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
27b30 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
27b40 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
27b50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27b60 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
27b70 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
27b80 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
27b90 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
27ba0 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
27bb0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
27bc0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
27bd0 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
27be0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
27bf0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
27c00 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
27c10 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
27c20 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
27c30 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  be returned.  Th
27c40 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
27c50 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
27c60 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
27c70 78 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  x 0..**.** If th
27c80 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
27c90 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  does not current
27ca0 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
27cb0 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
27cc0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64  he.** column ind
27cd0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
27ce0 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
27cf0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
27d00 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
27d10 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
27d20 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
27d30 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
27d40 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
27d50 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
27d60 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
27d70 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
27d80 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
27d90 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
27da0 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e  ize()] have been
27db0 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65   called subseque
27dc0 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
27dd0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
27de0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
27df0 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
27e00 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
27e10 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
27e20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
27e30 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
27e40 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
27e50 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
27e60 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
27e70 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
27e80 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
27e90 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
27ea0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
27eb0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
27ec0 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
27ed0 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
27ee0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
27ef0 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
27f00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
27f10 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
27f20 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
27f30 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
27f40 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
27f50 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
27f60 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
27f70 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
27f80 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
27f90 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
27fa0 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
27fb0 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
27fc0 20 63 6f 6c 75 6d 6e 2e 20 20 54 68 65 20 72 65   column.  The re
27fd0 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
27fe0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
27ff0 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
28000 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
28010 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
28020 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
28030 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65  LITE_NULL].  The
28040 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
28050 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
28060 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
28070 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
28080 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e  f no type.** con
28090 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
280a0 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69  curred as descri
280b0 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65  bed below.  Afte
280c0 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
280d0 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75  ion,.** the valu
280e0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
280f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
28100 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
28110 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
28120 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
28130 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
28140 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
28150 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
28160 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
28170 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
28180 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65  .**.** If the re
28190 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
281a0 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
281b0 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
281c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
281d0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
281e0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
281f0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
28200 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
28210 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
28220 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
28230 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
28240 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
28250 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
28260 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
28270 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
28280 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
28290 74 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72  tes..** If the r
282a0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
282b0 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
282c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
282d0 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
282e0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
282f0 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
28300 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
28310 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
28320 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
28330 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
28340 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
28350 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
28360 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
28370 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
28380 6d 69 6e 61 74 6f 72 20 61 74 20 74 68 65 20 65  minator at the e
28390 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
283a0 69 6e 67 2e 20 20 46 6f 72 20 63 6c 61 72 69 74  ing.  For clarit
283b0 79 3a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  y: the value ret
283c0 75 72 6e 65 64 20 69 73 20 74 68 65 20 6e 75 6d  urned is the num
283d0 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
283e0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
283f0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
28400 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
28410 2a 2a 20 53 74 72 69 6e 67 73 20 72 65 74 75 72  ** Strings retur
28420 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
28430 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
28440 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28450 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
28460 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
28470 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
28480 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68   terminated.  Th
28490 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
284a0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
284b0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
284c0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
284d0 4c 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74 72  LOB is an arbitr
284e0 61 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20  ary.** pointer, 
284f0 70 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20  possibly even a 
28500 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
28510 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
28520 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
28530 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
28540 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lar to sqlite3_c
28550 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
28560 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 20   but leaves the 
28570 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36  result in UTF-16
28580 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
28590 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66  order instead of
285a0 20 55 54 46 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a   UTF-8..** The z
285b0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
285c0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20 69  s not included i
285d0 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a  n this count..**
285e0 0a 2a 2a 20 54 68 65 20 6f 62 6a 65 63 74 20 72  .** The object r
285f0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
28600 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
28610 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
28620 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28630 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
28640 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64    An unprotected
28650 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
28660 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  bject.** may onl
28670 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b  y be used with [
28680 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
28690 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
286a0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
286b0 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
286c0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
286d0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
286e0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
286f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
28700 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
28710 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
28720 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
28730 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
28740 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
28750 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
28760 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
28770 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
28780 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
28790 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ()], then the be
287a0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
287b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ned..**.** These
287c0 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
287d0 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
287e0 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70   value where app
287f0 72 6f 70 72 69 61 74 65 2e 20 20 46 6f 72 0a 2a  ropriate.  For.*
28800 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
28810 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
28820 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
28830 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
28840 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
28850 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
28860 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
28870 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
28880 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
28890 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
288a0 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 66  atically.  The f
288b0 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
288c0 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65  etails the conve
288d0 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61  rsions.** that a
288e0 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a  re applied:.**.*
288f0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
28900 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
28910 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
28920 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70   Internal<br>Typ
28930 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  e <th> Requested
28940 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43  <br>Type <th>  C
28950 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onversion.**.** 
28960 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
28970 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
28980 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
28990 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
289a0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  ULL    <td>  FLO
289b0 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  AT    <td> Resul
289c0 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e  t is 0.0.** <tr>
289d0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
289e0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
289f0 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
28a00 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
28a10 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
28a20 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
28a30 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
28a40 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
28a50 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
28a60 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
28a70 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
28a80 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
28a90 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
28aa0 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <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 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
28ae0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
28af0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
28b00 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52   Same as INTEGER
28b10 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
28b20 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
28b30 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
28b40 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f  Convert from flo
28b50 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a  at to integer.**
28b60 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
28b70 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
28b80 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
28b90 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
28ba0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
28bb0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
28bc0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
28bd0 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54  e as FLOAT->TEXT
28be0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
28bf0 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  XT    <td> INTEG
28c00 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  ER   <td> Use at
28c10 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
28c20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
28c30 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73  FLOAT    <td> Us
28c40 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
28c50 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
28c60 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
28c70 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
28c80 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
28c90 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
28ca0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
28cb0 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
28cc0 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
28cd0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
28ce0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
28cf0 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
28d00 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a  en use atof().**
28d10 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
28d20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
28d30 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
28d40 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
28d50 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
28d60 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
28d70 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  te>.**.** The ta
28d80 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
28d90 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
28da0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
28db0 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
28dc0 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
28dd0 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
28de0 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
28df0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
28e00 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
28e10 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
28e20 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
28e30 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
28e40 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
28e50 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
28e60 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
28e70 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
28e80 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
28e90 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
28ea0 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
28eb0 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
28ec0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
28ed0 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
28ee0 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
28ef0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
28f00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
28f10 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
28f20 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
28f30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
28f40 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
28f50 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
28f60 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
28f70 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
28f80 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
28f90 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
28fa0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
28fb0 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
28fc0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
28fd0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
28fe0 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
28ff0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
29000 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
29010 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
29020 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
29030 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
29040 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
29050 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
29060 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
29070 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
29080 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
29090 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
290a0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
290b0 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
290c0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
290d0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
290e0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
290f0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
29100 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
29110 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
29120 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
29130 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
29140 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
29150 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
29160 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
29170 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29180 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
29190 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
291a0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
291b0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
291c0 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
291d0 0a 2a 2a 0a 2a 2a 20 43 6f 6e 76 65 72 73 69 6f  .**.** Conversio
291e0 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
291f0 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
29200 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
29210 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
29220 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
29230 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
29240 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
29250 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
29260 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
29270 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
29280 20 70 6f 69 6e 74 65 72 20 70 6f 69 6e 74 73 20   pointer points 
29290 74 6f 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  to will have bee
292a0 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
292b0 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
292c0 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
292d0 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
292e0 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
292f0 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
29300 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
29310 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
29320 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
29330 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
29340 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
29350 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20   The safest and 
29360 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d  easiest to remem
29370 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  ber policy is to
29380 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
29390 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
293a0 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
293b0 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
293c0 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
293d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
293e0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
293f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
29400 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
29410 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
29420 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
29430 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
29440 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
29450 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
29460 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
29470 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
29480 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
29490 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
294a0 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
294b0 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
294c0 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
294d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
294e0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
294f0 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
29500 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
29510 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
29520 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
29530 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
29540 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
29550 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
29560 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
29570 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
29580 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
29590 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
295a0 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
295b0 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
295c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
295d0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
295e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
295f0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
29600 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
29610 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
29620 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
29630 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
29640 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
29650 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
29660 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
29670 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tes()..**.** The
29680 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
29690 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74  ed are valid unt
296a0 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  il a type conver
296b0 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a  sion occurs as.*
296c0 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76  * described abov
296d0 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c  e, or until [sql
296e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
296f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
29700 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
29710 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
29720 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 6d 65 6d  called.  The mem
29730 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
29740 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
29750 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
29760 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
29770 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f  ly.  Do <b>not</
29780 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  b> pass the poin
29790 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
297a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
297b0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
297c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
297d0 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20  ], etc. into.** 
297e0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
297f0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 6d 65 6d  ..**.** If a mem
29800 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
29810 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
29820 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
29830 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
29840 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
29850 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
29860 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
29870 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
29880 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
29890 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
298a0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
298b0 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
298c0 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
298d0 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
298e0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
298f0 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
29900 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
29910 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  NOMEM]..**.** IN
29920 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
29930 7b 48 31 33 38 30 33 7d 20 54 68 65 20 5b 73 71  {H13803} The [sq
29940 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
29950 62 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  b(S,N)] interfac
29960 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
29970 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63  *          Nth c
29980 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
29990 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
299a0 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a  result set for.*
299b0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
299c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
299d0 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 42 4c 4f  nt] S into a BLO
299e0 42 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  B and then retur
299f0 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  ns a.**         
29a00 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
29a10 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e  converted value.
29a20 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 36 7d 20  .**.** {H13806} 
29a30 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
29a40 75 6d 6e 5f 62 79 74 65 73 28 53 2c 4e 29 5d 20  umn_bytes(S,N)] 
29a50 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29a60 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
29a70 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65    number of byte
29a80 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f 72  s in the BLOB or
29a90 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69   string (exclusi
29aa0 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ve of the.**    
29ab0 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69        zero termi
29ac0 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72  nator on the str
29ad0 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65  ing) that was re
29ae0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
29af0 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72            most r
29b00 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
29b10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
29b20 6f 62 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20  ob(S,N)] or.**  
29b30 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
29b40 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e  _column_text(S,N
29b50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30  )]..**.** {H1380
29b60 39 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  9} The [sqlite3_
29b70 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 53  column_bytes16(S
29b80 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
29b90 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20  eturns the.**   
29ba0 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66         number of
29bb0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
29bc0 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20  ring (exclusive 
29bd0 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
29be0 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74     zero terminat
29bf0 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67  or on the string
29c00 29 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  ) that was retur
29c10 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20  ned by the.**   
29c20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65         most rece
29c30 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
29c40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
29c50 36 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  6(S,N)]..**.** {
29c60 48 31 33 38 31 32 7d 20 54 68 65 20 5b 73 71 6c  H13812} The [sql
29c70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
29c80 6c 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  le(S,N)] interfa
29c90 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
29ca0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
29cb0 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
29cc0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
29cd0 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20   result set for 
29ce0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
29cf0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29d00 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 66 6c  ent] S into a fl
29d10 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
29d20 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  ue and.**       
29d30 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70     returns a cop
29d40 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e  y of that value.
29d50 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31 35 7d 20  .**.** {H13815} 
29d60 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
29d70 75 6d 6e 5f 69 6e 74 28 53 2c 4e 29 5d 20 69 6e  umn_int(S,N)] in
29d80 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
29d90 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
29da0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
29db0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
29dc0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
29dd0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
29de0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
29df0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
29e00 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64   a 64-bit signed
29e10 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20   integer and.** 
29e20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
29e30 20 74 68 65 20 6c 6f 77 65 72 20 33 32 20 62 69   the lower 32 bi
29e40 74 73 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67  ts of that integ
29e50 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31  er..**.** {H1381
29e60 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  8} The [sqlite3_
29e70 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 53 2c 4e  column_int64(S,N
29e80 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
29e90 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
29ea0 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
29eb0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
29ec0 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
29ed0 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a  t set for the.**
29ee0 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61            [prepa
29ef0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
29f00 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73   into a 64-bit s
29f10 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
29f20 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
29f30 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  turns a copy of 
29f40 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  that integer..**
29f50 0a 2a 2a 20 7b 48 31 33 38 32 31 7d 20 54 68 65  .** {H13821} The
29f60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
29f70 5f 74 65 78 74 28 53 2c 4e 29 5d 20 69 6e 74 65  _text(S,N)] inte
29f80 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
29f90 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
29fa0 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65  th column in the
29fb0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
29fc0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66  the result set f
29fd0 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  or.**          t
29fe0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
29ff0 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61  tement] S into a
2a000 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2a010 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20   UTF-8.**       
2a020 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
2a030 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2a040 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
2a050 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 34 7d 20 54  **.** {H13824} T
2a060 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
2a070 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 20  mn_text16(S,N)] 
2a080 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72  interface conver
2a090 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ts the.**       
2a0a0 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e     Nth column in
2a0b0 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77   the current row
2a0c0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2a0d0 65 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  et for the.**   
2a0e0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
2a0f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
2a100 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2a110 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20  ated 2-byte.**  
2a120 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20          aligned 
2a130 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
2a140 74 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67 20  te order string 
2a150 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20  and returns.**  
2a160 20 20 20 20 20 20 20 20 61 20 70 6f 69 6e 74 65          a pointe
2a170 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
2a180 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32 37 7d  ..**.** {H13827}
2a190 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
2a1a0 6c 75 6d 6e 5f 74 79 70 65 28 53 2c 4e 29 5d 20  lumn_type(S,N)] 
2a1b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2a1c0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e  s.**          on
2a1d0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  e of [SQLITE_NUL
2a1e0 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  L], [SQLITE_INTE
2a1f0 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c  GER], [SQLITE_FL
2a200 4f 41 54 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  OAT],.**        
2a210 20 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c    [SQLITE_TEXT],
2a220 20 6f 72 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42   or [SQLITE_BLOB
2a230 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74 65  ] as appropriate
2a240 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
2a250 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2a260 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
2a270 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2a280 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20   set for.**     
2a290 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61 72       the [prepar
2a2a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
2a2b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 33 30 7d 20  .**.** {H13830} 
2a2c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
2a2d0 75 6d 6e 5f 76 61 6c 75 65 28 53 2c 4e 29 5d 20  umn_value(S,N)] 
2a2e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2a2f0 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  s a.**          
2a300 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 75  pointer to an [u
2a310 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2a320 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2a330 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
2a340 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
2a350 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
2a360 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2a370 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20   set for.**     
2a380 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61 72       the [prepar
2a390 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
2a3a0 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
2a3b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2a3c0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2a3d0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2a3e0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2a3f0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
2a400 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2a410 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2a420 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
2a430 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2a440 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  Col);.double sql
2a450 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
2a460 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
2a470 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2a480 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a490 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
2a4a0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
2a4b0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
2a4c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
2a4d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a4e0 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
2a4f0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
2a500 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a510 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
2a520 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
2a530 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2a540 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2a550 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a560 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2a570 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2a580 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2a590 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
2a5a0 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74  te3_value *sqlit
2a5b0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2a5c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a5d0 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
2a5e0 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
2a5f0 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
2a600 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b  atement Object {
2a610 48 31 33 33 30 30 7d 20 3c 53 37 30 33 30 30 3e  H13300} <S70300>
2a620 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30100>.**.** T
2a630 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
2a640 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
2a650 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
2a660 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
2a670 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
2a680 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
2a690 61 73 20 65 78 65 63 75 74 65 64 20 73 75 63 63  as executed succ
2a6a0 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20  essfully or not 
2a6b0 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c  executed at all,
2a6c0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f   then.** SQLITE_
2a6d0 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  OK is returned. 
2a6e0 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  If execution of 
2a6f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61  the statement fa
2a700 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20  iled then an.** 
2a710 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20  [error code] or 
2a720 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
2a730 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
2a740 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  d..**.** This ro
2a750 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
2a760 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
2a770 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63   during the exec
2a780 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ution of the.** 
2a790 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a7a0 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20 76 69  ent].  If the vi
2a7b0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61  rtual machine ha
2a7c0 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s not.** complet
2a7d0 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65  ed execution whe
2a7e0 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  n this routine i
2a7f0 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69  s called, that i
2a800 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e  s like.** encoun
2a810 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20  tering an error 
2a820 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  or an [sqlite3_i
2a830 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72  nterrupt | inter
2a840 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d 70  rupt]..** Incomp
2a850 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61 79  lete updates may
2a860 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
2a870 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  and transactions
2a880 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64 65   canceled,.** de
2a890 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
2a8a0 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61 6e  ircumstances, an
2a8b0 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72 20  d the.** [error 
2a8c0 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20 77  code] returned w
2a8d0 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  ill be [SQLITE_A
2a8e0 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  BORT]..**.** INV
2a8f0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
2a900 48 31 31 33 30 32 7d 20 54 68 65 20 5b 73 71 6c  H11302} The [sql
2a910 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2a920 5d 20 69 6e 74 65 72 66 61 63 65 20 64 65 73 74  ] interface dest
2a930 72 6f 79 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  roys the.**     
2a940 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
2a950 74 61 74 65 6d 65 6e 74 5d 20 53 20 61 6e 64 20  tatement] S and 
2a960 72 65 6c 65 61 73 65 73 20 61 6c 6c 0a 2a 2a 20  releases all.** 
2a970 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20           memory 
2a980 61 6e 64 20 66 69 6c 65 20 72 65 73 6f 75 72 63  and file resourc
2a990 65 73 20 68 65 6c 64 20 62 79 20 74 68 61 74 20  es held by that 
2a9a0 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48  object..**.** {H
2a9b0 31 31 33 30 34 7d 20 49 66 20 74 68 65 20 6d 6f  11304} If the mo
2a9c0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2a9d0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2a9e0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  S)] for the.**  
2a9f0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
2aa00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
2aa10 65 74 75 72 6e 65 64 20 61 6e 20 65 72 72 6f 72  eturned an error
2aa20 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
2aa30 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
2aa40 6c 69 7a 65 28 53 29 5d 20 72 65 74 75 72 6e 73  lize(S)] returns
2aa50 20 74 68 61 74 20 73 61 6d 65 20 65 72 72 6f 72   that same error
2aa60 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2aa70 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
2aa80 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2aa90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2aaa0 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
2aab0 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
2aac0 63 74 20 7b 48 31 33 33 33 30 7d 20 3c 53 37 30  ct {H13330} <S70
2aad0 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  300>.**.** The s
2aae0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66  qlite3_reset() f
2aaf0 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
2ab00 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72  d to reset a [pr
2ab10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ab20 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b  ].** object back
2ab30 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
2ab40 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20  state, ready to 
2ab50 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a  be re-executed..
2ab60 2a 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65  ** Any SQL state
2ab70 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
2ab80 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
2ab90 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
2aba0 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
2abb0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
2abc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2abd0 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
2abe0 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
2abf0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
2ac00 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
2ac10 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
2ac20 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 32  s..**.** {H11332
2ac30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
2ac40 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
2ac50 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
2ac60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ac70 74 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20  t] S.**         
2ac80 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67   back to the beg
2ac90 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72  inning of its pr
2aca0 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ogram..**.** {H1
2acb0 31 33 33 34 7d 20 49 66 20 74 68 65 20 6d 6f 73  1334} If the mos
2acc0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2acd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2ace0 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20  )] for the.**   
2acf0 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
2ad00 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65   statement] S re
2ad10 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
2ad20 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OW] or [SQLITE_D
2ad30 4f 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ONE],.**        
2ad40 20 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    or if [sqlite3
2ad50 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65  _step(S)] has ne
2ad60 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20  ver before been 
2ad70 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20  called on S,.** 
2ad80 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73           then [s
2ad90 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2ada0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
2adb0 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  _OK]..**.** {H11
2adc0 33 33 36 7d 20 49 66 20 74 68 65 20 6d 6f 73 74  336} If the most
2add0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
2ade0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2adf0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  ] for the.**    
2ae00 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
2ae10 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
2ae20 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
2ae30 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
2ae40 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74    [sqlite3_reset
2ae50 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20  (S)] returns an 
2ae60 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
2ae70 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
2ae80 7b 48 31 31 33 33 38 7d 20 54 68 65 20 5b 73 71  {H11338} The [sq
2ae90 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2aea0 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
2aeb0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
2aec0 6c 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  lues.**         
2aed0 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
2aee0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
2aef0 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
2af00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2af10 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74   S..*/.int sqlit
2af20 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
2af30 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2af40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2af50 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
2af60 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
2af70 20 7b 48 31 36 31 30 30 7d 20 3c 53 32 30 32 30   {H16100} <S2020
2af80 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
2af90 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  {function creati
2afa0 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20  on routines}.** 
2afb0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
2afc0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2afd0 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20  QL function}.** 
2afe0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
2aff0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2b000 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  QL functions}.**
2b010 0a 2a 2a 20 54 68 65 73 65 20 74 77 6f 20 66 75  .** These two fu
2b020 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74  nctions (collect
2b030 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22  ively known as "
2b040 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
2b050 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20  n routines").** 
2b060 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
2b070 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
2b080 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74   aggregates or t
2b090 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
2b0a0 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78  ehavior.** of ex
2b0b0 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
2b0c0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
2b0d0 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69  es.  The only di
2b0e0 66 66 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e  fference between
2b0f0 20 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74   the.** two is t
2b100 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70  hat the second p
2b110 61 72 61 6d 65 74 65 72 2c 20 74 68 65 20 6e 61  arameter, the na
2b120 6d 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61  me of the (scala
2b130 72 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  r) function or.*
2b140 2a 20 61 67 67 72 65 67 61 74 65 2c 20 69 73 20  * aggregate, is 
2b150 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
2b160 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
2b170 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61  ate_function() a
2b180 6e 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72  nd UTF-16.** for
2b190 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2b1a0 66 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a  function16()..**
2b1b0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
2b1c0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
2b1d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2b1e0 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
2b1f0 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
2b200 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
2b210 2e 20 20 49 66 20 61 20 73 69 6e 67 6c 65 20 70  .  If a single p
2b220 72 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65  rogram uses more
2b230 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
2b240 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
2b250 20 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65   internally, the
2b260 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  n SQL functions 
2b270 6d 75 73 74 20 62 65 20 61 64 64 65 64 20 69 6e  must be added in
2b280 64 69 76 69 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a  dividually to.**
2b290 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
2b2a0 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onnection..**.**
2b2b0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
2b2c0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
2b2d0 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
2b2e0 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
2b2f0 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
2b300 6e 65 64 2e 20 20 54 68 65 20 6c 65 6e 67 74 68  ned.  The length
2b310 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20   of the name is 
2b320 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62  limited to 255 b
2b330 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20  ytes, exclusive 
2b340 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74  of.** the zero-t
2b350 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65  erminator.  Note
2b360 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c   that the name l
2b370 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
2b380 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20  n bytes, not.** 
2b390 63 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79  characters.  Any
2b3a0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
2b3b0 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
2b3c0 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
2b3d0 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
2b3e0 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  in [SQLITE_ERROR
2b3f0 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
2b400 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72  ..**.** The thir
2b410 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
2b420 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
2b430 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
2b440 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2b450 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
2b460 65 73 2e 20 49 66 20 74 68 69 73 20 70 61 72 61  es. If this para
2b470 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76  meter is negativ
2b480 65 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  e, then the SQL 
2b490 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2b4a0 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
2b4b0 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
2b4c0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
2b4d0 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
2b4e0 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
2b4f0 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a   specifies what.
2b500 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
2b510 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  | text encoding]
2b520 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69   this SQL functi
2b530 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a  on prefers for.*
2b540 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73  * its parameters
2b550 2e 20 20 41 6e 79 20 53 51 4c 20 66 75 6e 63 74  .  Any SQL funct
2b560 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
2b570 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 61 62 6c  on should be abl
2b580 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 6f 72  e to work.** wor
2b590 6b 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54  k with UTF-8, UT
2b5a0 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31  F-16le, or UTF-1
2b5b0 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69  6be.  But some i
2b5c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
2b5d0 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66  ay be.** more ef
2b5e0 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65  ficient with one
2b5f0 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61   encoding than a
2b600 6e 6f 74 68 65 72 2e 20 20 49 74 20 69 73 20 61  nother.  It is a
2b610 6c 6c 6f 77 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  llowed to.** inv
2b620 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  oke sqlite3_crea
2b630 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72  te_function() or
2b640 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2b650 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c  function16() mul
2b660 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77  tiple.** times w
2b670 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e  ith the same fun
2b680 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64  ction but with d
2b690 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20  ifferent values 
2b6a0 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20  of eTextRep..** 
2b6b0 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d  When multiple im
2b6c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2b6d0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2b6e0 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  on are available
2b6f0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  , SQLite.** will
2b700 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68   pick the one th
2b710 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20  at involves the 
2b720 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
2b730 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  data conversion.
2b740 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20  .** If there is 
2b750 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d  only a single im
2b760 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69  plementation whi
2b770 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  ch does not care
2b780 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e   what text.** en
2b790 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20  coding is used, 
2b7a0 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
2b7b0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
2b7c0 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e  be [SQLITE_ANY].
2b7d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68  .**.** The fifth
2b7e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
2b7f0 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
2b800 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
2b810 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
2b820 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
2b830 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
2b840 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
2b850 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
2b860 61 74 61 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  ata()]..**.** Th
2b870 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74  e seventh, eight
2b880 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61  h and ninth para
2b890 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
2b8a0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
2b8b0 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
2b8c0 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
2b8d0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
2b8e0 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
2b8f0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2b900 67 67 72 65 67 61 74 65 2e 20 41 20 73 63 61 6c  ggregate. A scal
2b910 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
2b920 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
2b930 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
2b940 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
2b950 61 63 6b 20 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70  ack only, NULL p
2b960 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62  ointers should b
2b970 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
2b980 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c  xStep and xFinal
2b990 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
2b9a0 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
2b9b0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2b9c0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
2b9d0 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
2b9e0 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
2b9f0 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70  NULL should be p
2ba00 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
2ba10 20 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78   To delete an ex
2ba20 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
2ba30 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
2ba40 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66  ate, pass NULL f
2ba50 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
2ba60 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e  ction callbacks.
2ba70 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 70 65 72  .**.** It is per
2ba80 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
2ba90 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
2baa0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
2bab0 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
2bac0 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
2bad0 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
2bae0 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
2baf0 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
2bb00 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
2bb10 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
2bb20 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
2bb30 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73    SQLite will us
2bb40 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  e.** the impleme
2bb50 6e 74 61 74 69 6f 6e 20 6d 6f 73 74 20 63 6c 6f  ntation most clo
2bb60 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65  sely matches the
2bb70 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68   way in which th
2bb80 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  e.** SQL functio
2bb90 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
2bba0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
2bbb0 2a 2a 20 7b 48 31 36 31 30 33 7d 20 54 68 65 20  ** {H16103} The 
2bbc0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2bbd0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 69 6e  function16()] in
2bbe0 74 65 72 66 61 63 65 20 62 65 68 61 76 65 73 20  terface behaves 
2bbf0 65 78 61 63 74 6c 79 0a 2a 2a 20 20 20 20 20 20  exactly.**      
2bc00 20 20 20 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65      like [sqlite
2bc10 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2bc20 6e 28 29 5d 20 69 6e 20 65 76 65 72 79 20 77 61  n()] in every wa
2bc30 79 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  y except that it
2bc40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
2bc50 65 72 70 72 65 74 73 20 74 68 65 20 7a 46 75 6e  erprets the zFun
2bc60 63 74 69 6f 6e 4e 61 6d 65 20 61 72 67 75 6d 65  ctionName argume
2bc70 6e 74 20 61 73 20 7a 65 72 6f 2d 74 65 72 6d 69  nt as zero-termi
2bc80 6e 61 74 65 64 20 55 54 46 2d 31 36 0a 2a 2a 20  nated UTF-16.** 
2bc90 20 20 20 20 20 20 20 20 20 6e 61 74 69 76 65 20           native 
2bca0 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74 65  byte order inste
2bcb0 61 64 20 6f 66 20 61 73 20 7a 65 72 6f 2d 74 65  ad of as zero-te
2bcc0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 2e 0a  rminated UTF-8..
2bcd0 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 36 7d 20 41  **.** {H16106} A
2bce0 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f   successful invo
2bcf0 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20  cation of.**    
2bd00 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74        the [sqlit
2bd10 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2bd20 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d  on(D,X,N,E,...)]
2bd30 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
2bd40 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ters.**         
2bd50 20 6f 72 20 72 65 70 6c 61 63 65 73 20 63 61 6c   or replaces cal
2bd60 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
2bd70 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  in the [database
2bd80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a   connection] D.*
2bd90 2a 20 20 20 20 20 20 20 20 20 20 75 73 65 64 20  *          used 
2bda0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  to implement the
2bdb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61   SQL function na
2bdc0 6d 65 64 20 58 20 77 69 74 68 20 4e 20 70 61 72  med X with N par
2bdd0 61 6d 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20  ameters.**      
2bde0 20 20 20 20 61 6e 64 20 68 61 76 69 6e 67 20 61      and having a
2bdf0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
2be00 65 6e 63 6f 64 69 6e 67 20 6f 66 20 45 2e 0a 2a  encoding of E..*
2be10 2a 0a 2a 2a 20 7b 48 31 36 31 30 39 7d 20 41 20  *.** {H16109} A 
2be20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
2be30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
2be40 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2be50 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a  N,E,P,F,S,L)].**
2be60 20 20 20 20 20 20 20 20 20 20 72 65 70 6c 61 63            replac
2be70 65 73 20 74 68 65 20 50 2c 20 46 2c 20 53 2c 20  es the P, F, S, 
2be80 61 6e 64 20 4c 20 76 61 6c 75 65 73 20 66 72 6f  and L values fro
2be90 6d 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c  m any prior call
2bea0 73 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  s with.**       
2beb0 20 20 20 74 68 65 20 73 61 6d 65 20 44 2c 20 58     the same D, X
2bec0 2c 20 4e 2c 20 61 6e 64 20 45 20 76 61 6c 75 65  , N, and E value
2bed0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 32  s..**.** {H16112
2bee0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2bef0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2bf00 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  ,X,...)] interfa
2bf10 63 65 20 66 61 69 6c 73 20 77 69 74 68 0a 2a 2a  ce fails with.**
2bf20 20 20 20 20 20 20 20 20 20 20 61 20 72 65 74 75            a retu
2bf30 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  rn code of [SQLI
2bf40 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 74 68 65  TE_ERROR] if the
2bf50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6e 61   SQL function na
2bf60 6d 65 20 58 20 69 73 0a 2a 2a 20 20 20 20 20 20  me X is.**      
2bf70 20 20 20 20 6c 6f 6e 67 65 72 20 74 68 61 6e 20      longer than 
2bf80 32 35 35 20 62 79 74 65 73 20 65 78 63 6c 75 73  255 bytes exclus
2bf90 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 20  ive of the zero 
2bfa0 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
2bfb0 2a 20 7b 48 31 36 31 31 38 7d 20 45 69 74 68 65  * {H16118} Eithe
2bfc0 72 20 46 20 6d 75 73 74 20 62 65 20 4e 55 4c 4c  r F must be NULL
2bfd0 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65   and S and L are
2bfe0 20 6e 6f 6e 2d 4e 55 4c 4c 20 6f 72 20 65 6c 73   non-NULL or els
2bff0 65 20 46 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  e F.**          
2c000 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 20 61 6e 64 20  is non-NULL and 
2c010 53 20 61 6e 64 20 4c 20 61 72 65 20 4e 55 4c 4c  S and L are NULL
2c020 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 20  , otherwise.**  
2c030 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2c040 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c050 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c  (D,X,N,E,P,F,S,L
2c060 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
2c070 54 45 5f 45 52 52 4f 52 5d 2e 0a 2a 2a 0a 2a 2a  TE_ERROR]..**.**
2c080 20 7b 48 31 36 31 32 31 7d 20 54 68 65 20 5b 73   {H16121} The [s
2c090 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2c0a0 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69  nction(D,...)] i
2c0b0 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
2c0c0 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20  ith an.**       
2c0d0 20 20 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66     error code of
2c0e0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69   [SQLITE_BUSY] i
2c0f0 66 20 74 68 65 72 65 20 65 78 69 73 74 20 5b 70  f there exist [p
2c100 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c110 74 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ts].**          
2c120 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2c130 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2c140 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
2c150 2a 2a 20 7b 48 31 36 31 32 34 7d 20 54 68 65 20  ** {H16124} The 
2c160 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2c170 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e  function(D,X,N,.
2c180 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66  ..)] interface f
2c190 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20  ails with an.** 
2c1a0 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 63           error c
2c1b0 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45  ode of [SQLITE_E
2c1c0 52 52 4f 52 5d 20 69 66 20 70 61 72 61 6d 65 74  RROR] if paramet
2c1d0 65 72 20 4e 20 28 73 70 65 63 69 66 79 69 6e 67  er N (specifying
2c1e0 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 20   the number.**  
2c1f0 20 20 20 20 20 20 20 20 6f 66 20 61 72 67 75 6d          of argum
2c200 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51 4c 20  ents to the SQL 
2c210 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 72  function being r
2c220 65 67 69 73 74 65 72 65 64 29 20 69 73 20 6c 65  egistered) is le
2c230 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ss.**          t
2c240 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
2c250 72 20 74 68 61 6e 20 31 32 37 2e 0a 2a 2a 0a 2a  r than 127..**.*
2c260 2a 20 7b 48 31 36 31 32 37 7d 20 57 68 65 6e 20  * {H16127} When 
2c270 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  N is non-negativ
2c280 65 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  e, the [sqlite3_
2c290 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2c2a0 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  D,X,N,...)].**  
2c2b0 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
2c2c0 65 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63  e causes callbac
2c2d0 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ks to be invoked
2c2e0 20 66 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e   for the SQL fun
2c2f0 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
2c300 20 20 6e 61 6d 65 64 20 58 20 77 68 65 6e 20 74    named X when t
2c310 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
2c320 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 53 51  uments to the SQ
2c330 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  L function is.**
2c340 20 20 20 20 20 20 20 20 20 20 65 78 61 63 74 6c            exactl
2c350 79 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  y N..**.** {H161
2c360 33 30 7d 20 57 68 65 6e 20 4e 20 69 73 20 2d 31  30} When N is -1
2c370 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  , the [sqlite3_c
2c380 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2c390 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20  ,X,N,...)].**   
2c3a0 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
2c3b0 20 63 61 75 73 65 73 20 63 61 6c 6c 62 61 63 6b   causes callback
2c3c0 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  s to be invoked 
2c3d0 66 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63  for the SQL func
2c3e0 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
2c3f0 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 61 6e   named X with an
2c400 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
2c410 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ments..**.** {H1
2c420 36 31 33 33 7d 20 57 68 65 6e 20 63 61 6c 6c 73  6133} When calls
2c430 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
2c440 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58  ate_function(D,X
2c450 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20  ,N,...)].**     
2c460 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75 6c       specify mul
2c470 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
2c480 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2c490 65 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20  e function X.** 
2c4a0 20 20 20 20 20 20 20 20 20 61 6e 64 20 77 68 65           and whe
2c4b0 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d 65 6e 74 61  n one implementa
2c4c0 74 69 6f 6e 20 68 61 73 20 4e 3e 3d 30 20 61 6e  tion has N>=0 an
2c4d0 64 20 74 68 65 20 6f 74 68 65 72 20 68 61 73 20  d the other has 
2c4e0 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20 20 20 20 20  N=(-1).**       
2c4f0 20 20 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74     the implement
2c500 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
2c510 2d 7a 65 72 6f 20 4e 20 69 73 20 70 72 65 66 65  -zero N is prefe
2c520 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  rred..**.** {H16
2c530 31 33 36 7d 20 57 68 65 6e 20 63 61 6c 6c 73 20  136} When calls 
2c540 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
2c550 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2c560 4e 2c 45 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  N,E,...)].**    
2c570 20 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75        specify mu
2c580 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
2c590 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2c5a0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69  me function X wi
2c5b0 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  th.**          t
2c5c0 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f  he same number o
2c5d0 66 20 61 72 67 75 6d 65 6e 74 73 20 4e 20 62 75  f arguments N bu
2c5e0 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  t with different
2c5f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 63  .**          enc
2c600 6f 64 69 6e 67 73 20 45 2c 20 74 68 65 6e 20 74  odings E, then t
2c610 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2c620 6e 20 77 68 65 72 65 20 45 20 6d 61 74 63 68 65  n where E matche
2c630 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2c640 20 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64    database encod
2c650 69 6e 67 20 69 73 20 70 72 65 66 65 72 72 65 64  ing is preferred
2c660 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 33 39 7d  ..**.** {H16139}
2c670 20 46 6f 72 20 61 6e 20 61 67 67 72 65 67 61 74   For an aggregat
2c680 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  e SQL function c
2c690 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
2c6a0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
2c6b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2c6c0 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 30 2c 53 2c  n(D,X,N,E,P,0,S,
2c6d0 4c 29 5d 20 74 68 65 20 66 69 6e 61 6c 69 7a 65  L)] the finalize
2c6e0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 75  r.**          fu
2c6f0 6e 63 74 69 6f 6e 20 4c 20 77 69 6c 6c 20 61 6c  nction L will al
2c700 77 61 79 73 20 62 65 20 69 6e 76 6f 6b 65 64 20  ways be invoked 
2c710 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 69 66 20  exactly once if 
2c720 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2c730 73 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 53 20  step function S 
2c740 69 73 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  is called one or
2c750 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 0a   more times..**.
2c760 2a 2a 20 7b 48 31 36 31 34 32 7d 20 57 68 65 6e  ** {H16142} When
2c770 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
2c780 65 69 74 68 65 72 20 74 68 65 20 78 46 75 6e 63  either the xFunc
2c790 20 6f 72 20 78 53 74 65 70 20 66 75 6e 63 74 69   or xStep functi
2c7a0 6f 6e 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  on of.**        
2c7b0 20 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    an application
2c7c0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2c7d0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
2c7e0 74 65 20 63 72 65 61 74 65 64 0a 2a 2a 20 20 20  te created.**   
2c7f0 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74         by [sqlit
2c800 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2c810 6f 6e 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  on()] or [sqlite
2c820 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2c830 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  n16()],.**      
2c840 20 20 20 20 74 68 65 6e 20 74 68 65 20 61 72 72      then the arr
2c850 61 79 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76  ay of [sqlite3_v
2c860 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 20 70 61  alue] objects pa
2c870 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 20  ssed as the.**  
2c880 20 20 20 20 20 20 20 20 74 68 69 72 64 20 70 61          third pa
2c890 72 61 6d 65 74 65 72 20 61 72 65 20 61 6c 77 61  rameter are alwa
2c8a0 79 73 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ys [protected sq
2c8b0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2c8c0 65 63 74 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ects..*/.int sql
2c8d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2c8e0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
2c8f0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
2c900 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
2c910 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
2c920 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
2c930 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
2c940 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
2c950 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2c960 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2c970 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
2c980 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
2c990 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2c9a0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2c9b0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
2c9c0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
2c9d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2c9e0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
2c9f0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
2ca00 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
2ca10 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
2ca20 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
2ca30 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
2ca40 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
2ca50 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
2ca60 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2ca70 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2ca80 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
2ca90 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2caa0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2cab0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
2cac0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
2cad0 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ext*).);../*.** 
2cae0 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45  CAPI3REF: Text E
2caf0 6e 63 6f 64 69 6e 67 73 20 7b 48 31 30 32 36 37  ncodings {H10267
2cb00 7d 20 3c 53 35 30 32 30 30 3e 20 3c 48 31 36 31  } <S50200> <H161
2cb10 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
2cb20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20  constant define 
2cb30 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68  integer codes th
2cb40 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65  at represent the
2cb50 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74   various.** text
2cb60 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f   encodings suppo
2cb70 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  rted by SQLite..
2cb80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2cb90 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20  E_UTF8          
2cba0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
2cbb0 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20  E_UTF16LE       
2cbc0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
2cbd0 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20  E_UTF16BE       
2cbe0 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
2cbf0 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
2cc00 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
2cc10 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
2cc20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2cc30 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
2cc40 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  5    /* sqlite3_
2cc50 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20  create_function 
2cc60 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
2cc70 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
2cc80 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71  GNED  8    /* sq
2cc90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2cca0 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a  lation only */..
2ccb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ccc0 4f 62 73 6f 6c 65 74 65 20 46 75 6e 63 74 69 6f  Obsolete Functio
2ccd0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  ns.**.** These f
2cce0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c  unctions are all
2ccf0 20 6e 6f 77 20 6f 62 73 6f 6c 65 74 65 2e 20 20   now obsolete.  
2cd00 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
2cd10 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
2cd20 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
2cd30 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
2cd40 20 77 65 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   we continue to 
2cd50 73 75 70 70 6f 72 74 0a 2a 2a 20 74 68 65 73 65  support.** these
2cd60 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 48 6f 77   functions.  How
2cd70 65 76 65 72 2c 20 6e 65 77 20 64 65 76 65 6c 6f  ever, new develo
2cd80 70 6d 65 6e 74 20 70 72 6f 6a 65 63 74 73 20 73  pment projects s
2cd90 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
2cda0 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
2cdb0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
2cdc0 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
2cdd0 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
2cde0 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
2cdf0 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
2ce00 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
2ce10 20 79 6f 75 20 77 61 6e 74 20 74 68 65 79 20 64   you want they d
2ce20 6f 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  o..*/.int sqlite
2ce30 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
2ce40 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
2ce50 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  t*);.int sqlite3
2ce60 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
2ce70 5f 73 74 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c  _stmt*);.int sql
2ce80 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
2ce90 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
2cea0 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
2ceb0 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  mt*);.int sqlite
2cec0 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
2ced0 28 76 6f 69 64 29 3b 0a 76 6f 69 64 20 73 71 6c  (void);.void sql
2cee0 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61  ite3_thread_clea
2cef0 6e 75 70 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  nup(void);.int s
2cf00 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c  qlite3_memory_al
2cf10 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64  arm(void(*)(void
2cf20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  *,sqlite3_int64,
2cf30 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74  int),void*,sqlit
2cf40 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a  e3_int64);../*.*
2cf50 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
2cf60 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
2cf70 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
2cf80 75 65 73 20 7b 48 31 35 31 30 30 7d 20 3c 53 32  ues {H15100} <S2
2cf90 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0200>.**.** The 
2cfa0 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
2cfb0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
2cfc0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
2cfd0 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
2cfe0 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
2cff0 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
2d000 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
2d010 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
2d020 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
2d030 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
2d040 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
2d050 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
2d060 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
2d070 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
2d080 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
2d090 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
2d0a0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
2d0b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2d0c0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2d0d0 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
2d0e0 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
2d0f0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
2d100 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
2d110 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68  ates..** The 4th
2d120 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2d130 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
2d140 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
2d150 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
2d160 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2d170 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
2d180 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
2d190 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2d1a0 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
2d1b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2d1c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
2d1d0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2d1e0 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
2d1f0 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
2d200 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
2d210 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2d220 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2d230 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
2d240 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
2d250 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2d260 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
2d270 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
2d280 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
2d290 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2d2a0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
2d2b0 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
2d2c0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
2d2d0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  vior..**.** Thes
2d2e0 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
2d2f0 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f  just like the co
2d300 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c  rresponding [col
2d310 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
2d320 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20  ions].** except 
2d330 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74  that  these rout
2d340 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
2d350 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
2d360 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2d370 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
2d380 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
2d390 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
2d3a0 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
2d3b0 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
2d3c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2d3d0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2d3e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
2d3f0 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
2d400 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
2d410 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
2d420 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
2d430 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73  chine.  The.** s
2d440 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2d450 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
2d460 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2d470 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
2d480 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
2d490 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
2d4a0 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
2d4b0 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
2d4c0 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  tively..**.** Th
2d4d0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
2d4e0 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
2d4f0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2d500 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
2d510 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
2d520 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
2d530 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
2d540 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
2d550 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
2d560 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
2d570 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
2d580 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
2d590 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
2d5a0 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
2d5b0 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
2d5c0 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
2d5d0 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69  ther.** words, i
2d5e0 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
2d5f0 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
2d600 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
2d610 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
2d620 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
2d630 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73  ormed.  Otherwis
2d640 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
2d650 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b  occurs..** The [
2d660 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
2d670 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
2d680 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
2d690 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  eturned..**.** P
2d6a0 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63  lease pay partic
2d6b0 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74  ular attention t
2d6c0 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20  o the fact that 
2d6d0 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75  the pointer retu
2d6e0 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
2d6f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
2d700 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2d710 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a  lue_text()], or.
2d720 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2d730 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20  e_text16()] can 
2d740 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62  be invalidated b
2d750 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63  y a subsequent c
2d760 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2d770 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
2d780 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2d790 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73  e_bytes16()], [s
2d7a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2d7b0 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
2d7c0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2d7d0 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  6()]..**.** Thes
2d7e0 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
2d7f0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2d800 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61  he same thread a
2d810 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  s.** the SQL fun
2d820 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c  ction that suppl
2d830 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ied the [sqlite3
2d840 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74  _value*] paramet
2d850 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ers..**.** INVAR
2d860 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
2d870 35 31 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  5103} The [sqlit
2d880 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29  e3_value_blob(V)
2d890 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2d8a0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2d8b0 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
2d8c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2d8d0 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 42  bject V into a B
2d8e0 4c 4f 42 20 61 6e 64 20 74 68 65 6e 0a 2a 2a 20  LOB and then.** 
2d8f0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
2d900 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2d910 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61 6c 75  e converted valu
2d920 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 36  e..**.** {H15106
2d930 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  } The [sqlite3_v
2d940 61 6c 75 65 5f 62 79 74 65 73 28 56 29 5d 20 69  alue_bytes(V)] i
2d950 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2d960 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2d970 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2d980 20 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f 72 20   in the BLOB or 
2d990 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69 76  string (exclusiv
2d9a0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  e of the.**     
2d9b0 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e       zero termin
2d9c0 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72 69  ator on the stri
2d9d0 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65 74  ng) that was ret
2d9e0 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
2d9f0 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72 65           most re
2da00 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2da10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
2da20 28 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  (V)] or.**      
2da30 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c      [sqlite3_val
2da40 75 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a  ue_text(V)]..**.
2da50 2a 2a 20 7b 48 31 35 31 30 39 7d 20 54 68 65 20  ** {H15109} The 
2da60 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2da70 79 74 65 73 31 36 28 56 29 5d 20 69 6e 74 65 72  ytes16(V)] inter
2da80 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2da90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
2daa0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2dab0 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c  the string (excl
2dac0 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20  usive of the.** 
2dad0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65           zero te
2dae0 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20  rminator on the 
2daf0 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73  string) that was
2db00 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2db10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73  .**          mos
2db20 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2db30 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2db40 74 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20  text16(V)],.**  
2db50 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2db60 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
2db70 56 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  V)], or [sqlite3
2db80 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
2db90 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  V)]..**.** {H151
2dba0 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  12} The [sqlite3
2dbb0 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29  _value_double(V)
2dbc0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2dbd0 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2dbe0 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20       [protected 
2dbf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2dc00 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 66  bject V into a f
2dc10 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2dc20 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  lue and.**      
2dc30 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f      returns a co
2dc40 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c 75 65  py of that value
2dc50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 35 7d  ..**.** {H15115}
2dc60 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2dc70 6c 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65  lue_int(V)] inte
2dc80 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74  rface converts t
2dc90 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
2dca0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2dcb0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2dcc0 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20  V into a 64-bit 
2dcd0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
2dce0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
2dcf0 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72  eturns the lower
2dd00 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74   32 bits of that
2dd10 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
2dd20 7b 48 31 35 31 31 38 7d 20 54 68 65 20 5b 73 71  {H15118} The [sq
2dd30 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
2dd40 34 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  4(V)] interface 
2dd50 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2dd60 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
2dd70 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2dd80 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
2dd90 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64   a 64-bit signed
2dda0 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20   integer and.** 
2ddb0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
2ddc0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20   a copy of that 
2ddd0 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  integer..**.** {
2dde0 48 31 35 31 32 31 7d 20 54 68 65 20 5b 73 71 6c  H15121} The [sql
2ddf0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2de00 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
2de10 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2de20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
2de30 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2de40 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
2de50 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2de60 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20   UTF-8.**       
2de70 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
2de80 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2de90 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
2dea0 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 34 7d 20 54  **.** {H15124} T
2deb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2dec0 65 5f 74 65 78 74 31 36 28 56 29 5d 20 69 6e 74  e_text16(V)] int
2ded0 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20  erface converts 
2dee0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2def0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2df00 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2df10 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74   V into a zero-t
2df20 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74 65  erminated 2-byte
2df30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 69  .**          ali
2df40 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74 69  gned UTF-16 nati
2df50 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a  ve byte order.**
2df60 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67            string
2df70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
2df80 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73  ointer to that s
2df90 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  tring..**.** {H1
2dfa0 35 31 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74  5127} The [sqlit
2dfb0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
2dfc0 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(V)] interface 
2dfd0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2dfe0 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
2dff0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2e000 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
2e010 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
2e020 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20  ed 2-byte.**    
2e030 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54        aligned UT
2e040 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a  F-16 big-endian.
2e050 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
2e060 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
2e070 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
2e080 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
2e090 48 31 35 31 33 30 7d 20 54 68 65 20 5b 73 71 6c  H15130} The [sql
2e0a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2e0b0 36 6c 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  6le(V)] interfac
2e0c0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
2e0d0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
2e0e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e0f0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
2e100 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2e110 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20  ated 2-byte.**  
2e120 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20          aligned 
2e130 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e  UTF-16 little-en
2e140 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  dian.**         
2e150 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2e160 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2e170 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2e180 0a 2a 2a 20 7b 48 31 35 31 33 33 7d 20 54 68 65  .** {H15133} The
2e190 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2e1a0 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61  type(V)] interfa
2e1b0 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  ce returns.**   
2e1c0 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53         one of [S
2e1d0 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51  QLITE_NULL], [SQ
2e1e0 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b  LITE_INTEGER], [
2e1f0 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a  SQLITE_FLOAT],.*
2e200 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
2e210 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51  TE_TEXT], or [SQ
2e220 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70  LITE_BLOB] as ap
2e230 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a  propriate for.**
2e240 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73            the [s
2e250 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2e260 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ject V..**.** {H
2e270 31 35 31 33 36 7d 20 54 68 65 20 5b 73 71 6c 69  15136} The [sqli
2e280 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
2e290 63 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72  c_type(V)] inter
2e2a0 66 61 63 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  face converts.**
2e2b0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70            the [p
2e2c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2e2d0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56  _value] object V
2e2e0 20 69 6e 74 6f 20 65 69 74 68 65 72 20 61 6e 20   into either an 
2e2f0 69 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20  integer or.**   
2e300 20 20 20 20 20 20 20 61 20 66 6c 6f 61 74 69 6e         a floatin
2e310 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 69 66  g point value if
2e320 20 69 74 20 63 61 6e 20 64 6f 20 73 6f 20 77 69   it can do so wi
2e330 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a  thout loss of.**
2e340 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f 72 6d            inform
2e350 61 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72  ation, and retur
2e360 6e 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  ns one of [SQLIT
2e370 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20  E_NULL],.**     
2e380 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54       [SQLITE_INT
2e390 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46  EGER], [SQLITE_F
2e3a0 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
2e3b0 45 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  EXT], or.**     
2e3c0 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f       [SQLITE_BLO
2e3d0 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69 61 74  B] as appropriat
2e3e0 65 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  e for the.**    
2e3f0 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
2e400 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2e410 6f 62 6a 65 63 74 20 56 20 61 66 74 65 72 20 74  object V after t
2e420 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74  he conversion at
2e430 74 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  tempt..*/.const 
2e440 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
2e450 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  lue_blob(sqlite3
2e460 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2e470 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2e480 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  s(sqlite3_value*
2e490 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
2e4a0 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c  alue_bytes16(sql
2e4b0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f  ite3_value*);.do
2e4c0 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  uble sqlite3_val
2e4d0 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
2e4e0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2e4f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2e500 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2e510 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
2e520 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
2e530 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64(sqlite3_valu
2e540 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  e*);.const unsig
2e550 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
2e560 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
2e570 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
2e580 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2e590 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
2e5a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2e5b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2e5c0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2e5d0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
2e5e0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
2e5f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2e600 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
2e610 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2e620 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
2e630 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2e640 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2e650 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
2e660 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2e670 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e680 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
2e690 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
2e6a0 78 74 20 7b 48 31 36 32 31 30 7d 20 3c 53 32 30  xt {H16210} <S20
2e6b0 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  200>.**.** The i
2e6c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2e6d0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
2e6e0 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
2e6f0 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c  s routine to all
2e700 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72 75 63  ocate.** a struc
2e710 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69 6e 67  ture for storing
2e720 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a   their state..**
2e730 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69  .** The first ti
2e740 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
2e750 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2e760 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
2e770 6c 6c 65 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61  lled for a.** pa
2e780 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
2e790 74 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63  te, SQLite alloc
2e7a0 61 74 65 73 20 6e 42 79 74 65 73 20 6f 66 20 6d  ates nBytes of m
2e7b0 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75  emory, zeroes ou
2e7c0 74 20 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79  t that.** memory
2e7d0 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
2e7e0 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f  pointer to it. O
2e7f0 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
2e800 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
2e810 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
2e820 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2e830 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
2e840 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
2e850 69 6e 64 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61  index,.** the sa
2e860 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
2e870 75 72 6e 65 64 2e 20 54 68 65 20 69 6d 70 6c 65  urned. The imple
2e880 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
2e890 20 61 67 67 72 65 67 61 74 65 20 63 61 6e 20 75   aggregate can u
2e8a0 73 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  se.** the return
2e8b0 65 64 20 62 75 66 66 65 72 20 74 6f 20 61 63 63  ed buffer to acc
2e8c0 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a  umulate data..**
2e8d0 0a 2a 2a 20 53 51 4c 69 74 65 20 61 75 74 6f 6d  .** SQLite autom
2e8e0 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
2e8f0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 75 66  he allocated buf
2e900 66 65 72 20 77 68 65 6e 20 74 68 65 20 61 67 67  fer when the agg
2e910 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 72 79 20  regate.** query 
2e920 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
2e930 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
2e940 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 61  eter should be a
2e950 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
2e960 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
2e970 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
2e980 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
2e990 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
2e9a0 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
2e9b0 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
2e9c0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
2e9d0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
2e9e0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
2e9f0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
2ea00 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
2ea10 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
2ea20 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
2ea30 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2ea40 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
2ea50 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2ea60 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31  TS:.**.** {H1621
2ea70 31 7d 20 54 68 65 20 66 69 72 73 74 20 69 6e 76  1} The first inv
2ea80 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
2ea90 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2eaa0 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a  ntext(C,N)] for.
2eab0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 61  **          a pa
2eac0 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63  rticular instanc
2ead0 65 20 6f 66 20 61 6e 20 61 67 67 72 65 67 61 74  e of an aggregat
2eae0 65 20 66 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20  e function (for 
2eaf0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
2eb00 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78 74           context
2eb10 20 43 29 20 63 61 75 73 65 73 20 53 51 4c 69 74   C) causes SQLit
2eb20 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 4e 20  e to allocate N 
2eb30 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c  bytes of memory,
2eb40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72  .**          zer
2eb50 6f 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61  o that memory, a
2eb60 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e  nd return a poin
2eb70 74 65 72 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63  ter to the alloc
2eb80 61 74 65 64 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a  ated memory..**.
2eb90 2a 2a 20 7b 48 31 36 32 31 33 7d 20 49 66 20 61  ** {H16213} If a
2eba0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2ebb0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
2ebc0 64 75 72 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20  during.**       
2ebd0 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72     [sqlite3_aggr
2ebe0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
2ebf0 4e 29 5d 20 74 68 65 6e 20 74 68 65 20 66 75 6e  N)] then the fun
2ec00 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e  ction returns 0.
2ec10 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 35 7d 20  .**.** {H16215} 
2ec20 53 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  Second and subse
2ec30 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
2ec40 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  s of.**         
2ec50 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
2ec60 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
2ec70 5d 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 63  ] for the same c
2ec80 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 43  ontext pointer C
2ec90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 67 6e  .**          ign
2eca0 6f 72 65 20 74 68 65 20 4e 20 70 61 72 61 6d 65  ore the N parame
2ecb0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 20 61  ter and return a
2ecc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2ecd0 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
2ece0 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
2ecf0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2ed00 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74 69 6f   first invocatio
2ed10 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 37  n..**.** {H16217
2ed20 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  } The memory all
2ed30 6f 63 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74  ocated by [sqlit
2ed40 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2ed50 74 65 78 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a  text(C,N)] is.**
2ed60 20 20 20 20 20 20 20 20 20 20 61 75 74 6f 6d 61            automa
2ed70 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e  tically freed on
2ed80 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
2ed90 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2eda0 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
2edb0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2edc0 6c 69 7a 65 28 29 5d 20 66 6f 72 20 74 68 65 20  lize()] for the 
2edd0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ede0 65 6e 74 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a  ent] containing.
2edf0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2ee00 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
2ee10 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  on associated wi
2ee20 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f  th context C..*/
2ee30 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61  .void *sqlite3_a
2ee40 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2ee50 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2ee60 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
2ee70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ee80 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
2ee90 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 34 30  unctions {H16240
2eea0 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20200>.**.**
2eeb0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65   The sqlite3_use
2eec0 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  r_data() interfa
2eed0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
2eee0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
2eef0 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
2ef00 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
2ef10 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61  eter (the 5th pa
2ef20 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
2ef30 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2ef40 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
2ef50 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
2ef60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2ef70 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
2ef80 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
2ef90 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
2efa0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2efb0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e  ed function. {EN
2efc0 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  D}.**.** This ro
2efd0 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
2efe0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
2eff0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
2f000 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
2f010 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2f020 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
2f030 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  g..**.** INVARIA
2f040 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  NTS:.**.** {H162
2f050 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  43} The [sqlite3
2f060 5f 75 73 65 72 5f 64 61 74 61 28 43 29 5d 20 69  _user_data(C)] i
2f070 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2f080 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
2f090 2a 20 20 20 20 20 20 20 20 20 20 50 20 70 6f 69  *          P poi
2f0a0 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73  nter from the [s
2f0b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f0c0 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50  nction(D,X,N,E,P
2f0d0 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20  ,F,S,L)].**     
2f0e0 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33       or [sqlite3
2f0f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2f100 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53  16(D,X,N,E,P,F,S
2f110 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a  ,L)] call that.*
2f120 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73  *          regis
2f130 74 65 72 65 64 20 74 68 65 20 53 51 4c 20 66 75  tered the SQL fu
2f140 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65  nction associate
2f150 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
2f160 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76  context] C..*/.v
2f170 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65  oid *sqlite3_use
2f180 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  r_data(sqlite3_c
2f190 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
2f1a0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
2f1b0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46  ase Connection F
2f1c0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31  or Functions {H1
2f1d0 36 32 35 30 7d 20 3c 53 36 30 36 30 30 3e 3c 53  6250} <S60600><S
2f1e0 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
2f1f0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2f200 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
2f210 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2f220 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2f230 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
2f240 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f250 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
2f260 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
2f270 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2f280 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
2f290 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
2f2a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2f2b0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
2f2c0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
2f2d0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
2f2e0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2f2f0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ed function..**.
2f300 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2f310 2a 0a 2a 2a 20 7b 48 31 36 32 35 33 7d 20 54 68  *.** {H16253} Th
2f320 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
2f330 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 43 29 5d  xt_db_handle(C)]
2f340 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2f350 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
2f360 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44 20 70  .**          D p
2f370 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 20  ointer from the 
2f380 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2f390 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
2f3a0 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20  ,P,F,S,L)].**   
2f3b0 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
2f3c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2f3d0 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  on16(D,X,N,E,P,F
2f3e0 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74  ,S,L)] call that
2f3f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
2f400 69 73 74 65 72 65 64 20 74 68 65 20 53 51 4c 20  istered the SQL 
2f410 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61  function associa
2f420 74 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  ted with [sqlite
2f430 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f  3_context] C..*/
2f440 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
2f450 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
2f460 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  dle(sqlite3_cont
2f470 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
2f480 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e  PI3REF: Function
2f490 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 20   Auxiliary Data 
2f4a0 7b 48 31 36 32 37 30 7d 20 3c 53 32 30 32 30 30  {H16270} <S20200
2f4b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  >.**.** The foll
2f4c0 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69  owing two functi
2f4d0 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20  ons may be used 
2f4e0 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  by scalar SQL fu
2f4f0 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73  nctions to.** as
2f500 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61  sociate metadata
2f510 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76   with argument v
2f520 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61  alues. If the sa
2f530 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73  me value is pass
2f540 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c  ed to.** multipl
2f550 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  e invocations of
2f560 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75   the same SQL fu
2f570 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75  nction during qu
2f580 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75  ery execution, u
2f590 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72  nder.** some cir
2f5a0 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61  cumstances the a
2f5b0 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61  ssociated metada
2f5c0 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72  ta may be preser
2f5d0 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a  ved. This may.**
2f5e0 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78   be used, for ex
2f5f0 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20  ample, to add a 
2f600 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69  regular-expressi
2f610 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c  on matching scal
2f620 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20  ar.** function. 
2f630 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72  The compiled ver
2f640 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75  sion of the regu
2f650 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69  lar expression i
2f660 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d  s stored as.** m
2f670 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
2f680 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20  ed with the SQL 
2f690 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
2f6a0 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
2f6b0 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72  ession.** patter
2f6c0 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  n.  The compiled
2f6d0 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
2f6e0 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65  ion can be reuse
2f6f0 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  d on multiple.**
2f700 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
2f710 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2f720 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72  n so that the or
2f730 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73  iginal pattern s
2f740 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tring.** does no
2f750 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63  t need to be rec
2f760 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20  ompiled on each 
2f770 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  invocation..**.*
2f780 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
2f790 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
2f7a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2f7b0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
2f7c0 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
2f7d0 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
2f7e0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2f7f0 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
2f800 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
2f810 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
2f820 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2f830 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
2f840 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68  If no metadata h
2f850 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20  as been ever.** 
2f860 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65  been set for the
2f870 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66   Nth argument of
2f880 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f   the function, o
2f890 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70  r if the corresp
2f8a0 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  onding.** functi
2f8b0 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  on parameter has
2f8c0 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74   changed since t
2f8d0 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73  he meta-data was
2f8e0 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71   set,.** then sq
2f8f0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2f900 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  a() returns a NU
2f910 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
2f920 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65  * The sqlite3_se
2f930 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
2f940 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20  rface saves the 
2f950 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e  metadata.** poin
2f960 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72  ted to by its 3r
2f970 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
2f980 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  he metadata for 
2f990 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
2f9a0 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
2f9b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2f9c0 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65  function.  Subse
2f9d0 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
2f9e0 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  o sqlite3_get_au
2f9f0 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65  xdata() might re
2fa00 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20  turn this data, 
2fa10 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74  if it has.** not
2fa20 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e   been destroyed.
2fa30 0a 2a 2a 20 49 66 20 69 74 20 69 73 20 6e 6f 74  .** If it is not
2fa40 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69   NULL, SQLite wi
2fa50 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
2fa60 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63  structor.** func
2fa70 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68  tion given by th
2fa80 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2fa90 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
2faa0 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74  uxdata() on.** t
2fab0 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e  he metadata when
2fac0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
2fad0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ng function para
2fae0 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a  meter changes.**
2faf0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c   or when the SQL
2fb00 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c   statement compl
2fb10 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20  etes, whichever 
2fb20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a  comes first..**.
2fb30 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65  ** SQLite is fre
2fb40 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65  e to call the de
2fb50 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f  structor and dro
2fb60 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e  p metadata on an
2fb70 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f  y.** parameter o
2fb80 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61  f any function a
2fb90 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 54 68 65  t any time.  The
2fba0 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20   only guarantee 
2fbb0 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64  is that.** the d
2fbc0 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62  estructor will b
2fbd0 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20  e called before 
2fbe0 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
2fbf0 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  dropped..**.** I
2fc00 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61  n practice, meta
2fc10 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
2fc20 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
2fc30 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
2fc40 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74  expressions that
2fc50 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74   are constant at
2fc60 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54   compile time. T
2fc70 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74  his includes lit
2fc80 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
2fc90 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73  nd SQL variables
2fca0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
2fcb0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
2fcc0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
2fcd0 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
2fce0 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66  ich.** the SQL f
2fcf0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2fd00 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ng..**.** INVARI
2fd10 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ANTS:.**.** {H16
2fd20 32 37 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  272} The [sqlite
2fd30 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_get_auxdata(C,
2fd40 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
2fd50 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
2fd60 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 6d  **          to m
2fd70 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74  etadata associat
2fd80 65 64 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  ed with the Nth 
2fd90 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
2fda0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL function.**
2fdb0 20 20 20 20 20 20 20 20 20 20 77 68 6f 73 65 20            whose 
2fdc0 63 6f 6e 74 65 78 74 20 69 73 20 43 2c 20 6f 72  context is C, or
2fdd0 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20 69   NULL if there i
2fde0 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 61 73  s no metadata as
2fdf0 73 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20 20 20  sociated.**     
2fe00 20 20 20 20 20 77 69 74 68 20 74 68 61 74 20 70       with that p
2fe10 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
2fe20 7b 48 31 36 32 37 34 7d 20 54 68 65 20 5b 73 71  {H16274} The [sq
2fe30 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2fe40 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65  a(C,N,P,D)] inte
2fe50 72 66 61 63 65 20 61 73 73 69 67 6e 73 20 61 20  rface assigns a 
2fe60 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20  metadata.**     
2fe70 20 20 20 20 20 70 6f 69 6e 74 65 72 20 50 20 74       pointer P t
2fe80 6f 20 74 68 65 20 4e 74 68 20 70 61 72 61 6d 65  o the Nth parame
2fe90 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ter of the SQL f
2fea0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e  unction with con
2feb0 74 65 78 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48  text C..**.** {H
2fec0 31 36 32 37 36 7d 20 53 51 4c 69 74 65 20 77 69  16276} SQLite wi
2fed0 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
2fee0 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20  structor D with 
2fef0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
2ff00 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  t.**          wh
2ff10 69 63 68 20 69 73 20 74 68 65 20 6d 65 74 61 64  ich is the metad
2ff20 61 74 61 20 70 6f 69 6e 74 65 72 20 50 20 66 6f  ata pointer P fo
2ff30 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
2ff40 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
2ff50 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2ff60 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 77 68 65  ta(C,N,P,D)] whe
2ff70 6e 20 53 51 4c 69 74 65 20 63 65 61 73 65 73 20  n SQLite ceases 
2ff80 74 6f 20 68 6f 6c 64 0a 2a 2a 20 20 20 20 20 20  to hold.**      
2ff90 20 20 20 20 74 68 65 20 6d 65 74 61 64 61 74 61      the metadata
2ffa0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 37 7d  ..**.** {H16277}
2ffb0 20 53 51 4c 69 74 65 20 63 65 61 73 65 73 20 74   SQLite ceases t
2ffc0 6f 20 68 6f 6c 64 20 6d 65 74 61 64 61 74 61 20  o hold metadata 
2ffd0 66 6f 72 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  for an SQL funct
2ffe0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ion parameter.**
2fff0 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 20 74            when t
30000 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  he value of that
30010 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67   parameter chang
30020 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37  es..**.** {H1627
30030 38 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  8} When [sqlite3
30040 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
30050 2c 50 2c 44 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ,P,D)] is invoke
30060 64 2c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  d, the destructo
30070 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  r.**          is
30080 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 6e 79 20   called for any 
30090 70 72 69 6f 72 20 6d 65 74 61 64 61 74 61 20 61  prior metadata a
300a0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
300b0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
300c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
300d0 74 65 78 74 20 43 20 61 6e 64 20 70 61 72 61 6d  text C and param
300e0 65 74 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48  eter N..**.** {H
300f0 31 36 32 37 39 7d 20 53 51 4c 69 74 65 20 77 69  16279} SQLite wi
30100 6c 6c 20 63 61 6c 6c 20 64 65 73 74 72 75 63 74  ll call destruct
30110 6f 72 73 20 66 6f 72 20 61 6e 79 20 6d 65 74 61  ors for any meta
30120 64 61 74 61 20 69 74 20 69 73 20 68 6f 6c 64 69  data it is holdi
30130 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ng.**          i
30140 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 5b  n a particular [
30150 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30160 6e 74 5d 20 53 20 77 68 65 6e 20 65 69 74 68 65  nt] S when eithe
30170 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
30180 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
30190 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
301a0 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63 61 6c  alize(S)] is cal
301b0 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  led..*/.void *sq
301c0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
301d0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
301e0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64  t*, int N);.void
301f0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
30200 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
30210 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f  text*, int N, vo
30220 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f  id*, void (*)(vo
30230 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  id*));.../*.** C
30240 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e  API3REF: Constan
30250 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63  ts Defining Spec
30260 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42  ial Destructor B
30270 65 68 61 76 69 6f 72 20 7b 48 31 30 32 38 30 7d  ehavior {H10280}
30280 20 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S30100>.**.** 
30290 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
302a0 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
302b0 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
302c0 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
302d0 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
302e0 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
302f0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
30300 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
30310 20 20 49 66 20 74 68 65 20 64 65 73 74 72 75 63    If the destruc
30320 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  tor.** argument 
30330 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  is SQLITE_STATIC
30340 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
30350 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e  the content poin
30360 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a  ter is constant.
30370 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65  ** and will neve
30380 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f  r change.  It do
30390 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
303a0 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 54 68  e destroyed.  Th
303b0 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e  e.** SQLITE_TRAN
303c0 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
303d0 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
303e0 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
303f0 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
30400 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
30410 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
30420 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
30430 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
30440 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
30450 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
30460 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
30470 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
30480 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
30490 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
304a0 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
304b0 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ers.  See ticket
304c0 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64   #2191..*/.typed
304d0 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
304e0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
304f0 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
30500 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
30510 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
30520 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
30530 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
30540 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
30550 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
30560 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
30570 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
30580 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
30590 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
305a0 6f 6e 20 7b 48 31 36 34 30 30 7d 20 3c 53 32 30  on {H16400} <S20
305b0 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  200>.**.** These
305c0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
305d0 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
305e0 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
305f0 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
30600 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
30610 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
30620 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
30630 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
30640 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
30650 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
30660 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
30670 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
30680 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
30690 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
306a0 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
306b0 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65  ke the [paramete
306c0 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c  r binding] famil
306d0 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  y of.** function
306e0 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76  s used to bind v
306f0 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61  alues to host pa
30700 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70  rameters in prep
30710 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e  ared statements.
30720 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65  .** Refer to the
30730 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
30740 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
30750 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
30760 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
30770 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
30780 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72  ult_blob() inter
30790 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
307a0 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
307b0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
307c0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
307d0 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73  be the BLOB whos
307e0 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69  e content is poi
307f0 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68  nted.** to by th
30800 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
30810 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20  er and which is 
30820 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65  N bytes long whe
30830 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74  re N is the.** t
30840 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a  hird parameter..
30850 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
30860 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
30870 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73  b() interfaces s
30880 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  et the result of
30890 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the 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 42 4c 4f  tion to be a BLO
308c0 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c  B containing all
308d0 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61   zero.** bytes a
308e0 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
308f0 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  ze, where N is t
30900 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
30910 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  2nd parameter..*
30920 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
30930 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29  _result_double()
30940 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
30950 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
30960 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
30970 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
30980 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74  on to be a float
30990 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
309a0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
309b0 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
309c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
309d0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
309e0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
309f0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
30a00 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75  functions.** cau
30a10 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  se the implement
30a20 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
30a30 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65  to throw an exce
30a40 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65  ption..** SQLite
30a50 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67   uses the string
30a60 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
30a70 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65  he.** 2nd parame
30a80 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72  ter of sqlite3_r
30a90 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
30aa0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30ab0 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20  error16().** as 
30ac0 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65  the text of an e
30ad0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 53  rror message.  S
30ae0 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
30af0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
30b00 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f  ssage string fro
30b10 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
30b20 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d  _error() as UTF-
30b30 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74  8. SQLite.** int
30b40 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69  erprets the stri
30b50 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
30b60 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
30b70 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   as UTF-16 in na
30b80 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64  tive.** byte ord
30b90 65 72 2e 20 20 49 66 20 74 68 65 20 74 68 69 72  er.  If the thir
30ba0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
30bb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
30bc0 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
30bd0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30be0 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  16() is negative
30bf0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
30c00 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a  es as the error.
30c10 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74  ** message all t
30c20 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74  ext up through t
30c30 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
30c40 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74  aracter..** If t
30c50 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
30c60 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
30c70 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a  sult_error() or.
30c80 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
30c90 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
30ca0 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e  on-negative then
30cb0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68   SQLite takes th
30cc0 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73  at many.** bytes
30cd0 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
30ce0 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  ) from the 2nd p
30cf0 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
30d00 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
30d10 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
30d20 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
30d30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30d40 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75  error16().** rou
30d50 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69  tines make a pri
30d60 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
30d70 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
30d80 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ext before.** th
30d90 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63  ey return.  Henc
30da0 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  e, the calling f
30db0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c  unction can deal
30dc0 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64  locate or.** mod
30dd0 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74  ify the text aft
30de0 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77  er they return w
30df0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
30e00 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
30e10 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
30e20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
30e30 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
30e40 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
30e50 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
30e60 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
30e70 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79   a function.  By
30e80 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65   default,.** the
30e90 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53   error code is S
30ea0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 41 20  QLITE_ERROR.  A 
30eb0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
30ec0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
30ed0 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
30ee0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
30ef0 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20  rror16() resets 
30f00 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  the error code t
30f10 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a  o SQLITE_ERROR..
30f20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
30f30 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28  3_result_toobig(
30f40 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
30f50 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
30f60 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69  ow an error.** i
30f70 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
30f80 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
30f90 69 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65  is to long to re
30fa0 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  present..**.** T
30fb0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
30fc0 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66  t_nomem() interf
30fd0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
30fe0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72  e to throw an er
30ff0 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e  ror.** indicatin
31000 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20  g that a memory 
31010 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
31020 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
31030 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
31040 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
31050 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
31060 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
31070 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
31080 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
31090 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64  he 32-bit signed
310a0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
310b0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
310c0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  nd argument..** 
310d0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
310e0 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72  lt_int64() inter
310f0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
31100 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
31110 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
31120 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
31130 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  n to be the 64-b
31140 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
31150 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
31160 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
31170 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
31180 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
31190 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  ull() interface 
311a0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
311b0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
311c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
311d0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
311e0 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  be NULL..**.** T
311f0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
31200 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  t_text(), sqlite
31210 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
31220 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  ),.** sqlite3_re
31230 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c  sult_text16le(),
31240 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
31250 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69  ult_text16be() i
31260 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74  nterfaces.** set
31270 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
31280 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
31290 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
312a0 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
312b0 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69   text string whi
312c0 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ch is represente
312d0 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d  d as UTF-8, UTF-
312e0 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
312f0 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  rder,.** UTF-16 
31300 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f  little endian, o
31310 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64  r UTF-16 big end
31320 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
31330 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b  y..** SQLite tak
31340 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75  es the text resu
31350 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c  lt from the appl
31360 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20  ication from.** 
31370 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
31380 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
31390 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
313a0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20  terfaces..** If 
313b0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
313c0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
313d0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
313e0 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
313f0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51  egative, then SQ
31400 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c  Lite takes resul
31410 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20  t text from the 
31420 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  2nd parameter.**
31430 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
31440 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
31450 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  r..** If the 3rd
31460 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
31470 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31480 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
31490 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  s.** is non-nega
314a0 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61  tive, then as ma
314b0 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ny bytes (not ch
314c0 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65  aracters) of the
314d0 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64   text.** pointed
314e0 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70   to by the 2nd p
314f0 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b  arameter are tak
31500 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63  en as the applic
31510 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a  ation-defined.**
31520 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74   function result
31530 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20  ..** If the 4th 
31540 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
31550 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31560 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
31570 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
31580 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20  esult_blob is a 
31590 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
315a0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61  , then SQLite ca
315b0 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63  lls that.** func
315c0 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74  tion as the dest
315d0 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65  ructor on the te
315e0 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
315f0 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a  t when it has.**
31600 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
31610 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
31620 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
31630 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
31640 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
31650 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 0a 2a   interfaces or.*
31660 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
31670 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
31680 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
31690 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65  LITE_STATIC, the
316a0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75  n SQLite.** assu
316b0 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78  mes that the tex
316c0 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
316d0 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20   is in constant 
316e0 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
316f0 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 69  ot.** copy the i
31700 74 20 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74  t or call a dest
31710 72 75 63 74 6f 72 20 77 68 65 6e 20 69 74 20 68  ructor when it h
31720 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
31730 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
31740 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72  * If the 4th par
31750 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
31760 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31770 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
31780 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
31790 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
317a0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
317b0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
317c0 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
317d0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
317e0 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
317f0 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
31800 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
31810 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
31820 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
31830 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
31840 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
31850 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
31860 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  s the result of.
31870 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
31880 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
31890 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79  ion to be a copy
318a0 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65   the.** [unprote
318b0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
318c0 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69  ue] object speci
318d0 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20  fied by the 2nd 
318e0 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 0a  parameter.  The.
318f0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
31900 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
31910 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ace makes a copy
31920 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
31930 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68  _value].** so th
31940 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
31950 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64  value] specified
31960 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
31970 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a  r may change or.
31980 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ** be deallocate
31990 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
319a0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72  result_value() r
319b0 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68  eturns without h
319c0 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65  arm..** A [prote
319d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
319e0 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61  ue] object may a
319f0 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68  lways be used wh
31a00 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f  ere an.** [unpro
31a10 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
31a20 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20  alue] object is 
31a30 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74  required, so eit
31a40 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b  her.** kind of [
31a50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
31a60 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65  bject can be use
31a70 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65  d with this inte
31a80 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rface..**.** If 
31a90 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
31aa0 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  re called from w
31ab0 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72  ithin the differ
31ac0 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68  ent thread.** th
31ad0 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61  an the one conta
31ae0 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63  ining the applic
31af0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
31b00 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65  nction that rece
31b10 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ived.** the [sql
31b20 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f  ite3_context] po
31b30 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c  inter, the resul
31b40 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
31b50 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
31b60 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30  TS:.**.** {H1640
31b70 33 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20 72  3} The default r
31b80 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
31b90 20 61 6e 79 20 53 51 4c 20 66 75 6e 63 74 69 6f   any SQL functio
31ba0 6e 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  n is NULL..**.**
31bb0 20 7b 48 31 36 34 30 36 7d 20 54 68 65 20 5b 73   {H16406} The [s
31bc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
31bd0 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74  ob(C,V,N,D)] int
31be0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
31bf0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
31c00 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
31c10 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
31c20 61 20 42 4c 4f 42 20 74 68 61 74 20 69 73 20 4e  a BLOB that is N
31c30 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20   bytes.**       
31c40 20 20 20 69 6e 20 6c 65 6e 67 74 68 20 61 6e 64     in length and
31c50 20 77 69 74 68 20 63 6f 6e 74 65 6e 74 20 70 6f   with content po
31c60 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2e 0a 2a  inted to by V..*
31c70 2a 0a 2a 2a 20 7b 48 31 36 34 30 39 7d 20 54 68  *.** {H16409} Th
31c80 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
31c90 74 5f 64 6f 75 62 6c 65 28 43 2c 56 29 5d 20 69  t_double(C,V)] i
31ca0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
31cb0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
31cc0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
31cd0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
31ce0 65 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  e the floating p
31cf0 6f 69 6e 74 20 76 61 6c 75 65 20 56 2e 0a 2a 2a  oint value V..**
31d00 0a 2a 2a 20 7b 48 31 36 34 31 32 7d 20 54 68 65  .** {H16412} The
31d10 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
31d20 5f 65 72 72 6f 72 28 43 2c 56 2c 4e 29 5d 20 69  _error(C,V,N)] i
31d30 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
31d40 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20   the return.**  
31d50 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
31d60 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
31d70 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77  e an exception w
31d80 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  ith error code.*
31d90 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49  *          [SQLI
31da0 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20 61 20  TE_ERROR] and a 
31db0 55 54 46 2d 38 20 65 72 72 6f 72 20 6d 65 73 73  UTF-8 error mess
31dc0 61 67 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20  age copied from 
31dd0 56 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 20  V up to the.**  
31de0 20 20 20 20 20 20 20 20 66 69 72 73 74 20 7a 65          first ze
31df0 72 6f 20 62 79 74 65 20 6f 72 20 75 6e 74 69 6c  ro byte or until
31e00 20 4e 20 62 79 74 65 73 20 61 72 65 20 72 65 61   N bytes are rea
31e10 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69  d if N is positi
31e20 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31  ve..**.** {H1641
31e30 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
31e40 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 43  result_error16(C
31e50 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,V,N)] interface
31e60 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
31e70 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
31e80 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
31e90 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63  n C to be an exc
31ea0 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f  eption with erro
31eb0 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20  r code.**       
31ec0 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52     [SQLITE_ERROR
31ed0 5d 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 6e  ] and a UTF-16 n
31ee0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
31ef0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
31f00 2a 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 65  *          copie
31f10 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f 20 74  d from V up to t
31f20 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
31f30 72 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69  rminator or unti
31f40 6c 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20  l N bytes.**    
31f50 20 20 20 20 20 20 61 72 65 20 72 65 61 64 20 69        are read i
31f60 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e  f N is positive.
31f70 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 38 7d 20  .**.** {H16418} 
31f80 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
31f90 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
31fa0 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (C)] interface c
31fb0 68 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72  hanges the retur
31fc0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61  n.**          va
31fd0 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  lue of the funct
31fe0 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65  ion C to be an e
31ff0 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72  xception with er
32000 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20  ror code.**     
32010 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54 4f 4f       [SQLITE_TOO
32020 42 49 47 5d 20 61 6e 64 20 61 6e 20 61 70 70 72  BIG] and an appr
32030 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65  opriate error me
32040 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ssage..**.** {H1
32050 36 34 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  6421} The [sqlit
32060 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
32070 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65 72 66  nomem(C)] interf
32080 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20  ace changes the 
32090 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
320a0 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20     value of the 
320b0 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65  function C to be
320c0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69   an exception wi
320d0 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  th error code.**
320e0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
320f0 45 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e 20  E_NOMEM] and an 
32100 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
32110 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
32120 20 7b 48 31 36 34 32 34 7d 20 54 68 65 20 5b 73   {H16424} The [s
32130 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32140 72 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69  ror_code(C,E)] i
32150 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
32160 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20   the return.**  
32170 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
32180 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 43 20   the function C 
32190 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74 69  to be an excepti
321a0 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f  on with error co
321b0 64 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20 20 20  de E..**        
321c0 20 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73    The error mess
321d0 61 67 65 20 74 65 78 74 20 69 73 20 75 6e 63 68  age text is unch
321e0 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  anged..**.** {H1
321f0 36 34 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74  6427} The [sqlit
32200 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 43 2c  e3_result_int(C,
32210 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  V)] interface ch
32220 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
32230 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
32240 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
32250 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69   to be the 32-bi
32260 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20  t integer value 
32270 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 30  V..**.** {H16430
32280 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
32290 65 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c 56 29  esult_int64(C,V)
322a0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
322b0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
322c0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
322d0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
322e0 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20  o be the 64-bit 
322f0 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e  integer value V.
32300 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 33 7d 20  .**.** {H16433} 
32310 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
32320 75 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e 74  ult_null(C)] int
32330 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
32340 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
32350 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
32360 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
32370 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  NULL..**.** {H16
32380 34 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  436} The [sqlite
32390 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c  3_result_text(C,
323a0 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66 61 63  V,N,D)] interfac
323b0 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a  e changes the.**
323c0 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e            return
323d0 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69   value of functi
323e0 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 55  on C to be the U
323f0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 20  TF-8 string.**  
32400 20 20 20 20 20 20 20 20 56 20 75 70 20 74 6f 20          V up to 
32410 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69  the first zero i
32420 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a  f N is negative.
32430 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 74  **          or t
32440 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65 73  he first N bytes
32450 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20 6e 6f   of V if N is no
32460 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  n-negative..**.*
32470 2a 20 7b 48 31 36 34 33 39 7d 20 54 68 65 20 5b  * {H16439} The [
32480 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
32490 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 20  ext16(C,V,N,D)] 
324a0 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
324b0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
324c0 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
324d0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
324e0 62 65 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61  be the UTF-16 na
324f0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a  tive byte order.
32500 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
32510 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20 66  ng V up to the f
32520 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69  irst zero if N i
32530 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20  s negative.**   
32540 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69         or the fi
32550 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56  rst N bytes of V
32560 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67   if N is non-neg
32570 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ative..**.** {H1
32580 36 34 34 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  6442} The [sqlit
32590 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
325a0 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74  be(C,V,N,D)] int
325b0 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
325c0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
325d0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
325e0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
325f0 74 68 65 20 55 54 46 2d 31 36 20 62 69 67 2d 65  the UTF-16 big-e
32600 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ndian.**        
32610 20 20 73 74 72 69 6e 67 20 56 20 75 70 20 74 6f    string V up to
32620 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
32630 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65  if N is negative
32640 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
32650 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74 65  the first N byte
32660 73 20 6f 72 20 56 20 69 66 20 4e 20 69 73 20 6e  s or V if N is n
32670 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a  on-negative..**.
32680 2a 2a 20 7b 48 31 36 34 34 35 7d 20 54 68 65 20  ** {H16445} The 
32690 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
326a0 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44  text16le(C,V,N,D
326b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61  )] interface cha
326c0 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  nges the.**     
326d0 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75       return valu
326e0 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20  e of function C 
326f0 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31 36  to be the UTF-16
32700 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a   little-endian.*
32710 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69 6e  *          strin
32720 67 20 56 20 75 70 20 74 6f 20 74 68 65 20 66 69  g V up to the fi
32730 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73  rst zero if N is
32740 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20   negative.**    
32750 20 20 20 20 20 20 6f 72 20 74 68 65 20 66 69 72        or the fir
32760 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20  st N bytes of V 
32770 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  if N is non-nega
32780 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  tive..**.** {H16
32790 34 34 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  448} The [sqlite
327a0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 43  3_result_value(C
327b0 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,V)] interface c
327c0 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
327d0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
327e0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
327f0 43 20 74 6f 20 62 65 20 74 68 65 20 5b 75 6e 70  C to be the [unp
32800 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
32810 5f 76 61 6c 75 65 5d 0a 2a 2a 20 20 20 20 20 20  _value].**      
32820 20 20 20 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a      object V..**
32830 0a 2a 2a 20 7b 48 31 36 34 35 31 7d 20 54 68 65  .** {H16451} The
32840 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
32850 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20  _zeroblob(C,N)] 
32860 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
32870 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
32880 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
32890 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
328a0 62 65 20 61 6e 20 4e 2d 62 79 74 65 20 42 4c 4f  be an N-byte BLO
328b0 42 20 6f 66 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a  B of all zeros..
328c0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 34 7d 20 54  **.** {H16454} T
328d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
328e0 6c 74 5f 65 72 72 6f 72 28 29 5d 20 61 6e 64 20  lt_error()] and 
328f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32900 65 72 72 6f 72 31 36 28 29 5d 0a 2a 2a 20 20 20  error16()].**   
32910 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
32920 73 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66  s make a copy of
32930 20 74 68 65 69 72 20 65 72 72 6f 72 20 6d 65 73   their error mes
32940 73 61 67 65 20 73 74 72 69 6e 67 73 20 62 65 66  sage strings bef
32950 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ore.**          
32960 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
32970 20 7b 48 31 36 34 35 37 7d 20 49 66 20 74 68 65   {H16457} If the
32980 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61   D destructor pa
32990 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
329a0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
329b0 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
329c0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
329d0 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c  result_text(C,V,
329e0 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  N,D)], [sqlite3_
329f0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c  result_text16(C,
32a00 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
32a10 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
32a20 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c  sult_text16be(C,
32a30 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,N,D)], or.**  
32a40 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
32a50 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
32a60 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68  (C,V,N,D)] is th
32a70 65 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49  e constant [SQLI
32a80 54 45 5f 53 54 41 54 49 43 5d 0a 2a 2a 20 20 20  TE_STATIC].**   
32a90 20 20 20 20 20 20 20 74 68 65 6e 20 6e 6f 20 64         then no d
32aa0 65 73 74 72 75 63 74 6f 72 20 69 73 20 65 76 65  estructor is eve
32ab0 72 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  r called on the 
32ac0 70 6f 69 6e 74 65 72 20 56 20 61 6e 64 20 53 51  pointer V and SQ
32ad0 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  Lite.**         
32ae0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 56 20   assumes that V 
32af0 69 73 20 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a  is immutable..**
32b00 0a 2a 2a 20 7b 48 31 36 34 36 30 7d 20 49 66 20  .** {H16460} If 
32b10 74 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72  the D destructor
32b20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
32b30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
32b40 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  ob(C,V,N,D)],.**
32b50 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
32b60 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43  e3_result_text(C
32b70 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74  ,V,N,D)], [sqlit
32b80 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
32b90 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20  (C,V,N,D)],.**  
32ba0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
32bb0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
32bc0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a  (C,V,N,D)], or.*
32bd0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
32be0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
32bf0 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73  6le(C,V,N,D)] is
32c00 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a   the constant.**
32c10 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
32c20 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65  E_TRANSIENT] the
32c30 6e 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73  n the interfaces
32c40 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
32c50 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
32c60 20 63 6f 6e 74 65 6e 74 20 6f 66 20 56 20 61 6e   content of V an
32c70 64 20 72 65 74 61 69 6e 73 20 74 68 65 20 63 6f  d retains the co
32c80 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36  py..**.** {H1646
32c90 33 7d 20 49 66 20 74 68 65 20 44 20 64 65 73 74  3} If the D dest
32ca0 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74 65 72  ructor parameter
32cb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
32cc0 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44  ult_blob(C,V,N,D
32cd0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
32ce0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32cf0 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20  text(C,V,N,D)], 
32d00 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32d10 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d  text16(C,V,N,D)]
32d20 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
32d30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32d40 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d  xt16be(C,V,N,D)]
32d50 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  , or.**         
32d60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
32d70 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c  _text16le(C,V,N,
32d80 44 29 5d 20 69 73 20 73 6f 6d 65 20 76 61 6c 75  D)] is some valu
32d90 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20  e other than.** 
32da0 20 20 20 20 20 20 20 20 20 74 68 65 20 63 6f 6e           the con
32db0 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 53  stants [SQLITE_S
32dc0 54 41 54 49 43 5d 20 61 6e 64 20 5b 53 51 4c 49  TATIC] and [SQLI
32dd0 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74 68  TE_TRANSIENT] th
32de0 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  en.**          S
32df0 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
32e00 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
32e10 20 44 20 77 69 74 68 20 56 20 61 73 20 69 74 73   D with V as its
32e20 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 0a 2a   only argument.*
32e30 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 20  *          when 
32e40 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
32e50 77 69 74 68 20 74 68 65 20 56 20 76 61 6c 75 65  with the V value
32e60 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
32e70 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
32e80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32e90 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
32ea0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
32eb0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
32ec0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
32ed0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32ee0 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71  double);.void sq
32ef0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32f00 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
32f10 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
32f20 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
32f30 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32f40 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
32f50 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
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 65 72 72  lite3_result_err
32f80 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65  or_toobig(sqlite
32f90 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
32fa0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
32fb0 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
32fc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
32fd0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32fe0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
32ff0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33000 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
33010 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
33020 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33030 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
33040 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
33050 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33060 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
33070 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
33080 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
33090 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
330a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
330b0 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
330c0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
330d0 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
330e0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
330f0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33100 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
33110 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
33120 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
33130 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
33140 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33150 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
33160 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
33170 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
33180 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
33190 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
331a0 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
331b0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
331c0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
331d0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
331e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
331f0 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  lt_value(sqlite3
33200 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
33210 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
33220 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33230 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
33240 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
33250 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33260 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
33270 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
33280 65 73 20 7b 48 31 36 36 30 30 7d 20 3c 53 32 30  es {H16600} <S20
33290 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  300>.**.** These
332a0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75   functions are u
332b0 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63  sed to add new c
332c0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
332d0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61  es to the.** [da
332e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
332f0 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20  n] specified as 
33300 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
33310 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  nt..**.** The na
33320 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f  me of the new co
33330 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
33340 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73   is specified as
33350 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
33360 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
33370 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
33380 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
33390 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
333a0 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
333b0 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73  -16 string for s
333c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
333d0 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20  llation16(). In 
333e0 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65  all cases.** the
333f0 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20   name is passed 
33400 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  as the second fu
33410 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
33420 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  .**.** The third
33430 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65   argument may be
33440 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73   one of the cons
33450 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54  tants [SQLITE_UT
33460 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  F8],.** [SQLITE_
33470 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c  UTF16LE] or [SQL
33480 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e  ITE_UTF16BE], in
33490 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74 68  dicating that th
334a0 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a  e user-supplied.
334b0 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63  ** routine expec
334c0 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64 20  ts to be passed 
334d0 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
334e0 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  ngs encoded usin
334f0 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d  g UTF-8,.** UTF-
33500 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  16 little-endian
33510 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d  , or UTF-16 big-
33520 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
33530 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69  vely. The.** thi
33540 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68  rd argument migh
33550 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54  t also be [SQLIT
33560 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
33570 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
33580 74 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65  t.** the routine
33590 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72   expects pointer
335a0 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64  s to 16-bit word
335b0 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73   aligned strings
335c0 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e  .** of UTF-16 in
335d0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
335e0 20 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f   order of the ho
335f0 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a  st computer..**.
33600 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
33610 74 68 65 20 75 73 65 72 20 73 75 70 70 6c 69 65  the user supplie
33620 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  d routine must b
33630 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
33640 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e  fifth.** argumen
33650 74 2e 20 20 49 66 20 69 74 20 69 73 20 4e 55 4c  t.  If it is NUL
33660 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 73  L, this is the s
33670 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e 67 20  ame as deleting 
33680 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
33690 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20 74 68   sequence (so th
336a0 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74  at SQLite cannot
336b0 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65   call it anymore
336c0 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d 65 20  )..** Each time 
336d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
336e0 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74 69 6f  supplied functio
336f0 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  n is invoked, it
33700 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 61 73   is passed.** as
33710 20 69 74 73 20 66 69 72 73 74 20 70 61 72 61 6d   its first param
33720 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66 20 74  eter a copy of t
33730 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65 64 20  he void* passed 
33740 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  as the fourth ar
33750 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
33760 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33770 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74  ation() or sqlit
33780 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
33790 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  ion16()..**.** T
337a0 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61 72 67  he remaining arg
337b0 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 61 70  uments to the ap
337c0 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
337d0 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65 20 74  ed routine are t
337e0 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65  wo strings,.** e
337f0 61 63 68 20 72 65 70 72 65 73 65 6e 74 65 64 20  ach represented 
33800 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20 64 61  by a (length, da
33810 74 61 29 20 70 61 69 72 20 61 6e 64 20 65 6e 63  ta) pair and enc
33820 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e 63 6f  oded in the enco
33830 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77 61 73  ding.** that was
33840 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
33850 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 77 68  hird argument wh
33860 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  en the collation
33870 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a   sequence was.**
33880 20 72 65 67 69 73 74 65 72 65 64 2e 20 7b 45 4e   registered. {EN
33890 44 7d 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  D}  The applicat
338a0 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c  ion defined coll
338b0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68  ation routine sh
338c0 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e  ould.** return n
338d0 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72  egative, zero or
338e0 20 70 6f 73 69 74 69 76 65 20 69 66 20 74 68 65   positive if the
338f0 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73   first string is
33900 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65   less than,.** e
33910 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61  qual to, or grea
33920 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63  ter than the sec
33930 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e  ond string. i.e.
33940 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54 52 49   (STRING1 - STRI
33950 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NG2)..**.** The 
33960 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
33970 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f  ollation_v2() wo
33980 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
33990 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
339a0 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
339b0 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e 20 65  at it takes an e
339c0 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20 77 68  xtra argument wh
339d0 69 63 68 20 69 73 20 61 20 64 65 73 74 72 75 63  ich is a destruc
339e0 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63  tor for.** the c
339f0 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  ollation.  The d
33a00 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
33a10 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63 6f 6c  led when the col
33a20 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73  lation is.** des
33a30 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20 70 61  troyed and is pa
33a40 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66 20 74  ssed a copy of t
33a50 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
33a60 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  ter void* pointe
33a70 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  r.** of the sqli
33a80 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33a90 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f  tion_v2()..** Co
33aa0 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64 65 73  llations are des
33ab0 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68 65 79  troyed when they
33ac0 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20   are overridden 
33ad0 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73 20 74  by later calls t
33ae0 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69  o the.** collati
33af0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63  on creation func
33b00 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68  tions or when th
33b10 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
33b20 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65  ection] is close
33b30 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
33b40 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  te3_close()]..**
33b50 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
33b60 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 33 7d 20 41  **.** {H16603} A
33b70 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
33b80 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
33b90 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65      [sqlite3_cre
33ba0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
33bb0 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69  (B,X,E,P,F,D)] i
33bc0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20 20 20  nterface.**     
33bd0 20 20 20 20 20 72 65 67 69 73 74 65 72 73 20 66       registers f
33be0 75 6e 63 74 69 6f 6e 20 46 20 61 73 20 74 68 65  unction F as the
33bf0 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63   comparison func
33c00 74 69 6f 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20  tion used to.** 
33c10 20 20 20 20 20 20 20 20 20 69 6d 70 6c 65 6d 65           impleme
33c20 6e 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f  nt collation X o
33c30 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
33c40 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f  connection] B fo
33c50 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61  r.**          da
33c60 74 61 62 61 73 65 73 20 68 61 76 69 6e 67 20 65  tabases having e
33c70 6e 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a  ncoding E..**.**
33c80 20 7b 48 31 36 36 30 34 7d 20 53 51 4c 69 74 65   {H16604} SQLite
33c90 20 75 6e 64 65 72 73 74 61 6e 64 73 20 74 68 65   understands the
33ca0 20 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a   X parameter to.
33cb0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
33cc0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33cd0 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
33ce0 2c 46 2c 44 29 5d 20 61 73 20 61 20 7a 65 72 6f  ,F,D)] as a zero
33cf0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20  -terminated.**  
33d00 20 20 20 20 20 20 20 20 55 54 46 2d 38 20 73 74          UTF-8 st
33d10 72 69 6e 67 20 69 6e 20 77 68 69 63 68 20 63 61  ring in which ca
33d20 73 65 20 69 73 20 69 67 6e 6f 72 65 64 20 66 6f  se is ignored fo
33d30 72 20 41 53 43 49 49 20 63 68 61 72 61 63 74 65  r ASCII characte
33d40 72 73 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  rs and.**       
33d50 20 20 20 69 73 20 73 69 67 6e 69 66 69 63 61 6e     is significan
33d60 74 20 66 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20  t for non-ASCII 
33d70 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
33d80 2a 20 7b 48 31 36 36 30 36 7d 20 53 75 63 63 65  * {H16606} Succe
33d90 73 73 69 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b  ssive calls to [
33da0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
33db0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c  ollation_v2(B,X,
33dc0 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20  E,P,F,D)].**    
33dd0 20 20 20 20 20 20 77 69 74 68 20 74 68 65 20 73        with the s
33de0 61 6d 65 20 76 61 6c 75 65 73 20 66 6f 72 20 42  ame values for B
33df0 2c 20 58 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72  , X, and E, over
33e00 72 69 64 65 20 70 72 69 6f 72 20 76 61 6c 75 65  ride prior value
33e10 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  s.**          of
33e20 20 50 2c 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a   P, F, and D..**
33e30 0a 2a 2a 20 7b 48 31 36 36 30 39 7d 20 49 66 20  .** {H16609} If 
33e40 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44  the destructor D
33e50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   in [sqlite3_cre
33e60 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
33e70 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a  (B,X,E,P,F,D)].*
33e80 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e 6f  *          is no
33e90 74 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74 20 69  t NULL then it i
33ea0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 72  s called with ar
33eb0 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 20 74 68  gument P when th
33ec0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
33ed0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
33ee0 20 69 73 20 64 72 6f 70 70 65 64 20 62 79 20 53   is dropped by S
33ef0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  QLite..**.** {H1
33f00 36 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e  6612} A collatin
33f10 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 72  g function is dr
33f20 6f 70 70 65 64 20 77 68 65 6e 20 69 74 20 69 73  opped when it is
33f30 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a   overloaded..**.
33f40 2a 2a 20 7b 48 31 36 36 31 35 7d 20 41 20 63 6f  ** {H16615} A co
33f50 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
33f60 20 69 73 20 64 72 6f 70 70 65 64 20 77 68 65 6e   is dropped when
33f70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
33f80 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
33f90 20 20 20 20 20 69 73 20 63 6c 6f 73 65 64 20 75       is closed u
33fa0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c  sing [sqlite3_cl
33fb0 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ose()]..**.** {H
33fc0 31 36 36 31 38 7d 20 54 68 65 20 70 6f 69 6e 74  16618} The point
33fd0 65 72 20 50 20 69 6e 20 5b 73 71 6c 69 74 65 33  er P in [sqlite3
33fe0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
33ff0 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44  n_v2(B,X,E,P,F,D
34000 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  )].**          i
34010 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
34020 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61   as the first pa
34030 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
34040 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20  omparison.**    
34050 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 46        function F
34060 20 66 6f 72 20 61 6c 6c 20 73 75 62 73 65 71 75   for all subsequ
34070 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ent invocations 
34080 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  of F..**.** {H16
34090 36 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b  621} A call to [
340a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
340b0 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50  ollation(B,X,E,P
340c0 2c 46 29 5d 20 69 73 20 65 78 61 63 74 6c 79 0a  ,F)] is exactly.
340d0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
340e0 73 61 6d 65 20 61 73 20 61 20 63 61 6c 6c 20 74  same as a call t
340f0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
34100 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
34110 5d 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  ] with.**       
34120 20 20 20 74 68 65 20 73 61 6d 65 20 70 61 72 61     the same para
34130 6d 65 74 65 72 73 20 61 6e 64 20 61 20 4e 55 4c  meters and a NUL
34140 4c 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a  L destructor..**
34150 0a 2a 2a 20 7b 48 31 36 36 32 34 7d 20 46 6f 6c  .** {H16624} Fol
34160 6c 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69 74 65  lowing a [sqlite
34170 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
34180 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
34190 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  D)],.**         
341a0 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
341b0 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63   comparison func
341c0 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74  tion F for all t
341d0 65 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a  ext comparison.*
341e0 2a 20 20 20 20 20 20 20 20 20 20 6f 70 65 72 61  *          opera
341f0 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 5b 64 61  tions on the [da
34200 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
34210 6e 5d 20 42 20 6f 6e 20 74 65 78 74 20 76 61 6c  n] B on text val
34220 75 65 73 20 74 68 61 74 0a 2a 2a 20 20 20 20 20  ues that.**     
34230 20 20 20 20 20 75 73 65 20 74 68 65 20 63 6f 6c       use the col
34240 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20  lating sequence 
34250 6e 61 6d 65 64 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b  named X..**.** {
34260 48 31 36 36 32 37 7d 20 54 68 65 20 5b 73 71 6c  H16627} The [sql
34270 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
34280 61 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c  ation16(B,X,E,P,
34290 46 29 5d 20 77 6f 72 6b 73 20 74 68 65 20 73 61  F)] works the sa
342a0 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  me.**          a
342b0 73 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  s [sqlite3_creat
342c0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c  e_collation(B,X,
342d0 45 2c 50 2c 46 29 5d 20 65 78 63 65 70 74 20 74  E,P,F)] except t
342e0 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  hat the.**      
342f0 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61      collation na
34300 6d 65 20 58 20 69 73 20 75 6e 64 65 72 73 74 6f  me X is understo
34310 6f 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  od as UTF-16 in 
34320 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
34330 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  r.**          in
34340 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a  stead of UTF-8..
34350 2a 2a 0a 2a 2a 20 7b 48 31 36 36 33 30 7d 20 57  **.** {H16630} W
34360 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d  hen multiple com
34370 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e  parison function
34380 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20  s are available 
34390 66 6f 72 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  for the same.** 
343a0 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61 74 69           collati
343b0 6e 67 20 73 65 71 75 65 6e 63 65 2c 20 53 51 4c  ng sequence, SQL
343c0 69 74 65 20 63 68 6f 6f 73 65 73 20 74 68 65 20  ite chooses the 
343d0 6f 6e 65 20 77 68 6f 73 65 20 74 65 78 74 20 65  one whose text e
343e0 6e 63 6f 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20  ncoding.**      
343f0 20 20 20 20 72 65 71 75 69 72 65 73 20 74 68 65      requires the
34400 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
34410 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
34420 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20   the default.** 
34430 20 20 20 20 20 20 20 20 20 74 65 78 74 20 65 6e           text en
34440 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 64 61  coding of the da
34450 74 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73  tabase..*/.int s
34460 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34470 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  llation(.  sqlit
34480 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
34490 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
344a0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
344b0 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  oid*,.  int(*xCo
344c0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
344d0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
344e0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
344f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
34500 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
34510 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
34520 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
34530 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
34540 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
34550 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
34560 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
34570 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
34580 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  void*),.  void(*
34590 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
345a0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
345b0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
345c0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
345d0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
345e0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78  Name,.  int eTex
345f0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
34600 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
34610 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
34620 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
34630 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
34640 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
34650 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
34660 6c 62 61 63 6b 73 20 7b 48 31 36 37 30 30 7d 20  lbacks {H16700} 
34670 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20300>.**.** T
34680 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74  o avoid having t
34690 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63  o register all c
346a0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
346b0 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61  es before a data
346c0 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75  base.** can be u
346d0 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61  sed, a single ca
346e0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
346f0 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
34700 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64  d with the.** [d
34710 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34720 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c 65 64  on] to be called
34730 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
34740 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
34750 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20  .** sequence is 
34760 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
34770 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
34780 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73  is registered us
34790 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
347a0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
347b0 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20  () API,.** then 
347c0 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65  it is passed the
347d0 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69   names of undefi
347e0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ned collation se
347f0 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e  quences as strin
34800 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e  gs.** encoded in
34810 20 55 54 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d   UTF-8. {H16703}
34820 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   If sqlite3_coll
34830 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
34840 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65   is used,.** the
34850 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65   names are passe
34860 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d  d as UTF-16 in m
34870 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79  achine native by
34880 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63  te order..** A c
34890 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75  all to either fu
348a0 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20  nction replaces 
348b0 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c  any existing cal
348c0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  lback..**.** Whe
348d0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  n the callback i
348e0 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66  s invoked, the f
348f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61  irst argument pa
34900 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a  ssed is a copy.*
34910 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  * of the second 
34920 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
34930 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
34940 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  eded() or.** sql
34950 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
34960 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20  eeded16().  The 
34970 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
34980 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  is the database.
34990 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
349a0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
349b0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
349c0 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
349d0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
349e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
349f0 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6LE], indicating
34a00 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61   the most desira
34a10 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20  ble form of the 
34a20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
34a30 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72  uence function r
34a40 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f  equired.  The fo
34a50 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
34a60 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
34a70 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f  e.** required co
34a80 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
34a90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ..**.** The call
34aa0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68  back function sh
34ab0 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68  ould register th
34ac0 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74  e desired collat
34ad0 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
34ae0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34af0 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  lation()], [sqli
34b00 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
34b10 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
34b20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34b30 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
34b40 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
34b50 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30  TS:.**.** {H1670
34b60 32 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  2} A successful 
34b70 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
34b80 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
34b90 64 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 20  d(D,P,F)].**    
34ba0 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
34bb0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
34bc0 65 64 31 36 28 44 2c 50 2c 46 29 5d 20 63 61 75  ed16(D,P,F)] cau
34bd0 73 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ses.**          
34be0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
34bf0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f 20 69  nnection] D to i
34c00 6e 76 6f 6b 65 20 63 61 6c 6c 62 61 63 6b 20 46  nvoke callback F
34c10 20 77 69 74 68 20 66 69 72 73 74 0a 2a 2a 20 20   with first.**  
34c20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65          paramete
34c30 72 20 50 20 77 68 65 6e 65 76 65 72 20 69 74 20  r P whenever it 
34c40 6e 65 65 64 73 20 61 20 63 6f 6d 70 61 72 69 73  needs a comparis
34c50 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20  on function for 
34c60 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  a.**          co
34c70 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63 65  llating sequence
34c80 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f   that it does no
34c90 74 20 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a  t know about..**
34ca0 0a 2a 2a 20 7b 48 31 36 37 30 34 7d 20 45 61 63  .** {H16704} Eac
34cb0 68 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  h successful cal
34cc0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
34cd0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
34ce0 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
34cf0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
34d00 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 20  ion_needed16()] 
34d10 6f 76 65 72 72 69 64 65 73 20 74 68 65 20 63 61  overrides the ca
34d20 6c 6c 62 61 63 6b 20 72 65 67 69 73 74 65 72 65  llback registere
34d30 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e  d.**          on
34d40 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
34d50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
34d60 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74  by prior calls t
34d70 6f 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20  o either.**     
34d80 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 2e 0a       interface..
34d90 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 36 7d 20 54  **.** {H16706} T
34da0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 72  he name of the r
34db0 65 71 75 65 73 74 65 64 20 63 6f 6c 6c 61 74 69  equested collati
34dc0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 73 73  ng function pass
34dd0 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20  ed in the.**    
34de0 20 20 20 20 20 20 34 74 68 20 70 61 72 61 6d 65        4th parame
34df0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
34e00 61 63 6b 20 69 73 20 69 6e 20 55 54 46 2d 38 20  ack is in UTF-8 
34e10 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  if the callback.
34e20 2a 2a 20 20 20 20 20 20 20 20 20 20 77 61 73 20  **          was 
34e30 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
34e40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
34e50 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e  ion_needed()] an
34e60 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  d.**          is
34e70 20 69 6e 20 55 54 46 2d 31 36 20 6e 61 74 69 76   in UTF-16 nativ
34e80 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20  e byte order if 
34e90 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73  the callback was
34ea0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
34eb0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73  istered using [s
34ec0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
34ed0 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f  _needed16()]..*/
34ee0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
34ef0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20  lation_needed(. 
34f00 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
34f10 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  id*, .  void(*)(
34f20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
34f30 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
34f40 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20  t char*).);.int 
34f50 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
34f60 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71  n_needed16(.  sq
34f70 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
34f80 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ,.  void(*)(void
34f90 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
34fa0 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f  TextRep,const vo
34fb0 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53  id*).);../*.** S
34fc0 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66  pecify the key f
34fd0 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20  or an encrypted 
34fe0 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20  database.  This 
34ff0 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62  routine should b
35000 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68  e.** called righ
35010 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  t after sqlite3_
35020 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  open()..**.** Th
35030 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
35040 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
35050 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
35060 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
35070 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
35080 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
35090 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  _key(.  sqlite3 
350a0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
350b0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
350c0 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
350d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
350e0 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
350f0 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20       /* The key 
35100 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61  */.);../*.** Cha
35110 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61  nge the key on a
35120 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e  n open database.
35130 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74    If the current
35140 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74   database is not
35150 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74  .** encrypted, t
35160 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
35170 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66   encrypt it.  If
35180 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77   pNew==0 or nNew
35190 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61  ==0, the.** data
351a0 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65  base is decrypte
351b0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  d..**.** The cod
351c0 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
351d0 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
351e0 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
351f0 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
35200 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
35210 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65  int sqlite3_reke
35220 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
35230 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
35240 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
35250 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
35260 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
35270 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
35280 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79    /* The new key
35290 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
352a0 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20  PI3REF: Suspend 
352b0 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20  Execution For A 
352c0 53 68 6f 72 74 20 54 69 6d 65 20 7b 48 31 30 35  Short Time {H105
352d0 33 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a  30} <S40410>.**.
352e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
352f0 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20  leep() function 
35300 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65  causes the curre
35310 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73  nt thread to sus
35320 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a  pend execution.*
35330 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61  * for at least a
35340 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
35350 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65  seconds specifie
35360 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74  d in its paramet
35370 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  er..**.** If the
35380 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
35390 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f  m does not suppo
353a0 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74  rt sleep request
353b0 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73  s with.** millis
353c0 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c  econd time resol
353d0 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ution, then the 
353e0 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75  time will be rou
353f0 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68  nded up to.** th
35400 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64  e nearest second
35410 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  . The number of 
35420 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
35430 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a  sleep actually.*
35440 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d  * requested from
35450 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
35460 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65  ystem is returne
35470 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  d..**.** SQLite 
35480 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20  implements this 
35490 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c  interface by cal
354a0 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28  ling the xSleep(
354b0 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74  ).** method of t
354c0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
354d0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
354e0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
354f0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 33  S:.**.** {H10533
35500 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  } The [sqlite3_s
35510 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61  leep(M)] interfa
35520 63 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  ce invokes the x
35530 53 6c 65 65 70 0a 2a 2a 20 20 20 20 20 20 20 20  Sleep.**        
35540 20 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20    method of the 
35550 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
35560 5f 76 66 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64  _vfs|VFS] in ord
35570 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  er to.**        
35580 20 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74    suspend execut
35590 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
355a0 6e 74 20 74 68 72 65 61 64 20 66 6f 72 20 61 74  nt thread for at
355b0 20 6c 65 61 73 74 0a 2a 2a 20 20 20 20 20 20 20   least.**       
355c0 20 20 20 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64     M millisecond
355d0 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 36  s..**.** {H10536
355e0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  } The [sqlite3_s
355f0 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72 66 61  leep(M)] interfa
35600 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
35610 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20  umber of.**     
35620 20 20 20 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64       millisecond
35630 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
35640 6c 6c 79 20 72 65 71 75 65 73 74 65 64 20 6f 66  lly requested of
35650 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a   the operating.*
35660 2a 20 20 20 20 20 20 20 20 20 20 73 79 73 74 65  *          syste
35670 6d 2c 20 77 68 69 63 68 20 6d 69 67 68 74 20 62  m, which might b
35680 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  e larger than th
35690 65 20 70 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a  e parameter M..*
356a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c  /.int sqlite3_sl
356b0 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  eep(int);../*.**
356c0 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
356d0 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f  Of The Folder Ho
356e0 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20  lding Temporary 
356f0 46 69 6c 65 73 20 7b 48 31 30 33 31 30 7d 20 3c  Files {H10310} <
35700 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66  S20000>.**.** If
35710 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72   this global var
35720 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f  iable is made to
35730 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69   point to a stri
35740 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74  ng which is.** t
35750 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c  he name of a fol
35760 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65  der (a.k.a. dire
35770 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c  ctory), then all
35780 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
35790 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53  .** created by S
357a0 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c  QLite will be pl
357b0 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72  aced in that dir
357c0 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73  ectory.  If this
357d0 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20   variable.** is 
357e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
357f0 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66  then SQLite perf
35800 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f  orms a search fo
35810 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  r an appropriate
35820 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
35830 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  le directory..**
35840 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
35850 66 65 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 69  fe to modify thi
35860 73 20 76 61 72 69 61 62 6c 65 20 6f 6e 63 65 20  s variable once 
35870 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
35880 65 63 74 69 6f 6e 5d 0a 2a 2a 20 68 61 73 20 62  ection].** has b
35890 65 65 6e 20 6f 70 65 6e 65 64 2e 20 20 49 74 20  een opened.  It 
358a0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
358b0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
358c0 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
358d0 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
358e0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
358f0 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
35900 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
35910 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
35920 20 62 65 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72   been call and r
35930 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 20  emain unchanged 
35940 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53  thereafter..*/.S
35950 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61  QLITE_EXTERN cha
35960 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  r *sqlite3_temp_
35970 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a  directory;../*.*
35980 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
35990 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74   For Auto-Commit
359a0 20 4d 6f 64 65 20 7b 48 31 32 39 33 30 7d 20 3c   Mode {H12930} <
359b0 53 36 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S60200>.** KEYWO
359c0 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74  RDS: {autocommit
359d0 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   mode}.**.** The
359e0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
359f0 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66  ocommit() interf
35a00 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ace returns non-
35a10 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20  zero or.** zero 
35a20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74  if the given dat
35a30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35a40 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e   is or is not in
35a50 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   autocommit mode
35a60 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ,.** respectivel
35a70 79 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  y.  Autocommit m
35a80 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66  ode is on by def
35a90 61 75 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d  ault..** Autocom
35aa0 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61  mit mode is disa
35ab0 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e  bled by a [BEGIN
35ac0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
35ad0 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
35ae0 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79  is re-enabled by
35af0 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b   a [COMMIT] or [
35b00 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a  ROLLBACK]..**.**
35b10 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64   If certain kind
35b20 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75  s of errors occu
35b30 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74  r on a statement
35b40 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d   within a multi-
35b50 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61  statement.** tra
35b60 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73  nsaction (errors
35b70 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49   including [SQLI
35b80 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_FULL], [SQLIT
35b90 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51  E_IOERR],.** [SQ
35ba0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51  LITE_NOMEM], [SQ
35bb0 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20  LITE_BUSY], and 
35bc0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
35bd0 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  T]) then the.** 
35be0 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68  transaction migh
35bf0 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t be rolled back
35c00 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
35c10 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f   The only way to
35c20 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65  .** find out whe
35c30 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f  ther SQLite auto
35c40 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
35c50 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61   back the transa
35c60 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61  ction after.** a
35c70 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73  n error is to us
35c80 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  e this function.
35c90 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
35ca0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 31  S:.**.** {H12931
35cb0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67  } The [sqlite3_g
35cc0 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 44 29  et_autocommit(D)
35cd0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
35ce0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a  rns non-zero or.
35cf0 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
35d00 20 69 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   if the [databas
35d10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
35d20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20  is or is not in 
35d30 61 75 74 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20 20  autocommit.**   
35d40 20 20 20 20 20 20 20 6d 6f 64 65 2c 20 72 65 73         mode, res
35d50 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
35d60 20 7b 48 31 32 39 33 32 7d 20 41 75 74 6f 63 6f   {H12932} Autoco
35d70 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20  mmit mode is on 
35d80 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
35d90 2a 20 7b 48 31 32 39 33 33 7d 20 41 75 74 6f 63  * {H12933} Autoc
35da0 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69  ommit mode is di
35db0 73 61 62 6c 65 64 20 62 79 20 61 20 73 75 63 63  sabled by a succ
35dc0 65 73 73 66 75 6c 20 5b 42 45 47 49 4e 5d 20 73  essful [BEGIN] s
35dd0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
35de0 7b 48 31 32 39 33 34 7d 20 41 75 74 6f 63 6f 6d  {H12934} Autocom
35df0 6d 69 74 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  mit mode is enab
35e00 6c 65 64 20 62 79 20 61 20 73 75 63 63 65 73 73  led by a success
35e10 66 75 6c 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20  ful [COMMIT] or 
35e20 5b 52 4f 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20 20  [ROLLBACK].**   
35e30 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74         statement
35e40 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49  ..**.** ASSUMPTI
35e50 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 39  ONS:.**.** {A129
35e60 33 36 7d 20 49 66 20 61 6e 6f 74 68 65 72 20 74  36} If another t
35e70 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68  hread changes th
35e80 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61  e autocommit sta
35e90 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62  tus of the datab
35ea0 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ase.**          
35eb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65  connection while
35ec0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
35ed0 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74   running, then t
35ee0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
35ef0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 75  **          is u
35f00 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  ndefined..*/.int
35f10 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
35f20 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a  ocommit(sqlite3*
35f30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35f40 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74  EF: Find The Dat
35f50 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20  abase Handle Of 
35f60 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
35f70 6d 65 6e 74 20 7b 48 31 33 31 32 30 7d 20 3c 53  ment {H13120} <S
35f80 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  60600>.**.** The
35f90 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64   sqlite3_db_hand
35fa0 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  le interface ret
35fb0 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61  urns the [databa
35fc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
35fd0 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63  andle.** to whic
35fe0 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  h a [prepared st
35ff0 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73  atement] belongs
36000 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20  .  The database 
36010 68 61 6e 64 6c 65 20 72 65 74 75 72 6e 65 64 20  handle returned 
36020 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62  by.** sqlite3_db
36030 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73  _handle is the s
36040 61 6d 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  ame database han
36050 64 6c 65 20 74 68 61 74 20 77 61 73 20 74 68 65  dle that was the
36060 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
36070 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
36080 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
36090 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61   call (or its va
360a0 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73  riants) that was
360b0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61   used to.** crea
360c0 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
360d0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c   in the first pl
360e0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ace..**.** INVAR
360f0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
36100 33 31 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  3123} The [sqlit
36110 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 53 29 5d  e3_db_handle(S)]
36120 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
36130 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
36140 20 20 20 20 20 20 20 20 20 74 6f 20 74 68 65 20           to the 
36150 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36160 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64  tion] associated
36170 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 20 20 20   with the.**    
36180 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
36190 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
361a0 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
361b0 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  3_db_handle(sqli
361c0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
361d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e  ** CAPI3REF: Fin
361e0 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61  d the next prepa
361f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 7b 48  red statement {H
36200 31 33 31 34 30 7d 20 3c 53 36 30 36 30 30 3e 0a  13140} <S60600>.
36210 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
36220 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
36230 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65  ointer to the ne
36240 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  xt [prepared sta
36250 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a  tement] after.**
36260 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65   pStmt associate
36270 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
36280 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
36290 20 70 44 62 2e 20 20 49 66 20 70 53 74 6d 74 20   pDb.  If pStmt 
362a0 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20  is NULL.** then 
362b0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72  this interface r
362c0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
362d0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72   to the first pr
362e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
362f0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
36300 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65  ith the database
36310 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e   connection pDb.
36320 20 20 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64    If no prepared
36330 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61   statement.** sa
36340 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64  tisfies the cond
36350 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72  itions of this r
36360 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72  outine, it retur
36370 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49  ns NULL..**.** I
36380 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
36390 20 7b 48 31 33 31 34 33 7d 20 49 66 20 44 20 69   {H13143} If D i
363a0 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  s a [database co
363b0 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 68  nnection] that h
363c0 6f 6c 64 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  olds one or more
363d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 75 6e 66  .**          unf
363e0 69 6e 61 6c 69 7a 65 64 20 5b 70 72 65 70 61 72  inalized [prepar
363f0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 61  ed statements] a
36400 6e 64 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  nd S is a NULL p
36410 6f 69 6e 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20  ointer,.**      
36420 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65      then [sqlite
36430 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53  3_next_stmt(D, S
36440 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c  )] routine shall
36450 20 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65   return a pointe
36460 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  r.**          to
36470 20 6f 6e 65 20 6f 66 20 74 68 65 20 70 72 65 70   one of the prep
36480 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20  ared statements 
36490 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
364a0 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 36  D..**.** {H13146
364b0 7d 20 49 66 20 44 20 69 73 20 61 20 5b 64 61 74  } If D is a [dat
364c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
364d0 5d 20 74 68 61 74 20 68 6f 6c 64 73 20 6e 6f 20  ] that holds no 
364e0 75 6e 66 69 6e 61 6c 69 7a 65 64 0a 2a 2a 20 20  unfinalized.**  
364f0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
36500 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e  d statements] an
36510 64 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  d S is a NULL po
36520 69 6e 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 20  inter, then.**  
36530 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
36540 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29  _next_stmt(D, S)
36550 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20  ] routine shall 
36560 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f  return a NULL po
36570 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  inter..**.** {H1
36580 33 31 34 39 7d 20 49 66 20 53 20 69 73 20 61 20  3149} If S is a 
36590 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
365a0 65 6e 74 5d 20 69 6e 20 74 68 65 20 5b 64 61 74  ent] in the [dat
365b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
365c0 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ] D.**          
365d0 61 6e 64 20 53 20 69 73 20 6e 6f 74 20 74 68 65  and S is not the
365e0 20 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73   last prepared s
365f0 74 61 74 65 6d 65 6e 74 20 69 6e 20 44 2c 20 74  tatement in D, t
36600 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
36610 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
36620 6d 74 28 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e  mt(D, S)] routin
36630 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 61  e shall return a
36640 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20   pointer.**     
36650 20 20 20 20 20 74 6f 20 74 68 65 20 6e 65 78 74       to the next
36660 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
36670 65 6e 74 20 69 6e 20 44 20 61 66 74 65 72 20 53  ent in D after S
36680 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 35 32 7d  ..**.** {H13152}
36690 20 49 66 20 53 20 69 73 20 74 68 65 20 6c 61 73   If S is the las
366a0 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  t [prepared stat
366b0 65 6d 65 6e 74 5d 20 69 6e 20 74 68 65 0a 2a 2a  ement] in the.**
366c0 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
366d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
366e0 44 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  D then the [sqli
366f0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c  te3_next_stmt(D,
36700 20 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20   S)].**         
36710 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72   routine shall r
36720 65 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  eturn a NULL poi
36730 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55  nter..**.** ASSU
36740 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  MPTIONS:.**.** {
36750 41 31 33 31 35 34 7d 20 54 68 65 20 5b 64 61 74  A13154} The [dat
36760 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36770 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61  ] pointer D in a
36780 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20   call to.**     
36790 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65       [sqlite3_ne
367a0 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75  xt_stmt(D,S)] mu
367b0 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f  st refer to an o
367c0 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  pen database.** 
367d0 20 20 20 20 20 20 20 20 20 63 6f 6e 6e 65 63 74           connect
367e0 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69  ion and in parti
367f0 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62  cular must not b
36800 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
36810 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d  ..*/.sqlite3_stm
36820 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  t *sqlite3_next_
36830 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44  stmt(sqlite3 *pD
36840 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  b, sqlite3_stmt 
36850 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
36860 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74  CAPI3REF: Commit
36870 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f   And Rollback No
36880 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62  tification Callb
36890 61 63 6b 73 20 7b 48 31 32 39 35 30 7d 20 3c 53  acks {H12950} <S
368a0 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  60400>.**.** The
368b0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
368c0 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
368d0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
368e0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
368f0 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
36900 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
36910 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74  action is commit
36920 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c  ted..** Any call
36930 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
36940 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
36950 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
36960 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
36970 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
36980 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
36990 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73  ridden..** The s
369a0 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
369b0 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
369c0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
369d0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
369e0 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
369f0 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
36a00 61 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74  action is commit
36a10 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c  ted..** Any call
36a20 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
36a30 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
36a40 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
36a50 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
36a60 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
36a70 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
36a80 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70  ridden..** The p
36a90 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20  Arg argument is 
36aa0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74  passed through t
36ab0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  o the callback..
36ac0 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61  ** If the callba
36ad0 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68  ck on a commit h
36ae0 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  ook function ret
36af0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a  urns non-zero,.*
36b00 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69  * then the commi
36b10 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69  t is converted i
36b20 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a  nto a rollback..
36b30 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
36b40 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72   function was pr
36b50 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
36b60 72 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67  red, its.** pArg
36b70 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
36b80 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e  ed.  Otherwise N
36b90 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
36ba0 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 69  .**.** Registeri
36bb0 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69  ng a NULL functi
36bc0 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  on disables the 
36bd0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
36be0 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
36bf0 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20   of this API, a 
36c00 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73  transaction is s
36c10 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e  aid to have been
36c20 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
36c30 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22  if an explicit "
36c40 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d  ROLLBACK" statem
36c50 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c  ent is executed,
36c60 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20   or.** an error 
36c70 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61  or constraint ca
36c80 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74  uses an implicit
36c90 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63   rollback to occ
36ca0 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62  ur..** The rollb
36cb0 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ack callback is 
36cc0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61  not invoked if a
36cd0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a   transaction is.
36ce0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
36cf0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63   rolled back bec
36d00 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73  ause the databas
36d10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
36d20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72  closed..** The r
36d30 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  ollback callback
36d40 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
36d50 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
36d60 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61   is.** rolled ba
36d70 63 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f 6d  ck because a com
36d80 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  mit callback ret
36d90 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a  urned non-zero..
36da0 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20  ** <todo> Check 
36db0 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a  on this </todo>.
36dc0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
36dd0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 31 7d  :.**.** {H12951}
36de0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
36df0 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  mmit_hook(D,F,P)
36e00 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
36e10 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20  sters the.**    
36e20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66        callback f
36e30 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20  unction F to be 
36e40 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67  invoked with arg
36e50 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72  ument P whenever
36e60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74  .**          a t
36e70 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69  ransaction commi
36e80 74 73 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ts on the [datab
36e90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36ea0 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 32  D..**.** {H12952
36eb0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
36ec0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50  ommit_hook(D,F,P
36ed0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
36ee0 75 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d  urns the P argum
36ef0 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ent.**          
36f00 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75  from the previou
36f10 73 20 63 61 6c 6c 20 77 69 74 68 20 74 68 65 20  s call with the 
36f20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
36f30 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a  onnection] D,.**
36f40 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c            or NUL
36f50 4c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 63  L on the first c
36f60 61 6c 6c 20 66 6f 72 20 61 20 70 61 72 74 69 63  all for a partic
36f70 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 63 6f  ular database co
36f80 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a  nnection D..**.*
36f90 2a 20 7b 48 31 32 39 35 33 7d 20 45 61 63 68 20  * {H12953} Each 
36fa0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
36fb0 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20  _commit_hook()] 
36fc0 6f 76 65 72 77 72 69 74 65 73 20 74 68 65 20 63  overwrites the c
36fd0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  allback.**      
36fe0 20 20 20 20 72 65 67 69 73 74 65 72 65 64 20 62      registered b
36ff0 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a  y prior calls..*
37000 2a 0a 2a 2a 20 7b 48 31 32 39 35 34 7d 20 49 66  *.** {H12954} If
37010 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e 74 20   the F argument 
37020 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  to [sqlite3_comm
37030 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  it_hook(D,F,P)] 
37040 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20  is NULL.**      
37050 20 20 20 20 74 68 65 6e 20 74 68 65 20 63 6f 6d      then the com
37060 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63  mit hook callbac
37070 6b 20 69 73 20 63 61 6e 63 65 6c 65 64 20 61 6e  k is canceled an
37080 64 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  d no callback.**
37090 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e 76            is inv
370a0 6f 6b 65 64 20 77 68 65 6e 20 61 20 74 72 61 6e  oked when a tran
370b0 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e  saction commits.
370c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 35 7d 20  .**.** {H12955} 
370d0 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 63 61  If the commit ca
370e0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
370f0 6f 6e 2d 7a 65 72 6f 20 74 68 65 6e 20 74 68 65  on-zero then the
37100 20 63 6f 6d 6d 69 74 20 69 73 0a 2a 2a 20 20 20   commit is.**   
37110 20 20 20 20 20 20 20 63 6f 6e 76 65 72 74 65 64         converted
37120 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b   into a rollback
37130 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 31 7d  ..**.** {H12961}
37140 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f   The [sqlite3_ro
37150 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c  llback_hook(D,F,
37160 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  P)] interface re
37170 67 69 73 74 65 72 73 20 74 68 65 0a 2a 2a 20 20  gisters the.**  
37180 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b          callback
37190 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62   function F to b
371a0 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  e invoked with a
371b0 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76  rgument P whenev
371c0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  er.**          a
371d0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c   transaction rol
371e0 6c 73 20 62 61 63 6b 20 6f 6e 20 74 68 65 20 5b  ls back on the [
371f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37200 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ion] D..**.** {H
37210 31 32 39 36 32 7d 20 54 68 65 20 5b 73 71 6c 69  12962} The [sqli
37220 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
37230 6b 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66  k(D,F,P)] interf
37240 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
37250 50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72  P.**          ar
37260 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  gument from the 
37270 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 77 69  previous call wi
37280 74 68 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20  th the same.**  
37290 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
372a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
372b0 20 6f 72 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20   or NULL on the 
372c0 66 69 72 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20  first call.**   
372d0 20 20 20 20 20 20 20 66 6f 72 20 61 20 70 61 72         for a par
372e0 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
372f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a   connection D..*
37300 2a 0a 2a 2a 20 7b 48 31 32 39 36 33 7d 20 45 61  *.** {H12963} Ea
37310 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ch call to [sqli
37320 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
37330 6b 28 29 5d 20 6f 76 65 72 77 72 69 74 65 73 20  k()] overwrites 
37340 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
37350 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65           registe
37360 72 65 64 20 62 79 20 70 72 69 6f 72 20 63 61 6c  red by prior cal
37370 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36  ls..**.** {H1296
37380 34 7d 20 49 66 20 74 68 65 20 46 20 61 72 67 75  4} If the F argu
37390 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
373a0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
373b0 2c 46 2c 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a  ,F,P)] is NULL.*
373c0 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
373d0 74 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f  the rollback hoo
373e0 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 61  k callback is ca
373f0 6e 63 65 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61  nceled and no ca
37400 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
37410 20 20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68     is invoked wh
37420 65 6e 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  en a transaction
37430 20 72 6f 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a   rolls back..*/.
37440 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
37450 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  mmit_hook(sqlite
37460 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
37470 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20  ), void*);.void 
37480 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  *sqlite3_rollbac
37490 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  k_hook(sqlite3*,
374a0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29   void(*)(void *)
374b0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
374c0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20   CAPI3REF: Data 
374d0 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74  Change Notificat
374e0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48  ion Callbacks {H
374f0 31 32 39 37 30 7d 20 3c 53 36 30 34 30 30 3e 0a  12970} <S60400>.
37500 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
37510 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20  3_update_hook() 
37520 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
37530 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
37540 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
37550 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
37560 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69  nnection] identi
37570 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
37580 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
37590 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
375a0 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70  ever a row is up
375b0 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
375c0 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41  or deleted..** A
375d0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
375e0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
375f0 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  ll to this funct
37600 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  ion.** for the s
37610 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
37620 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
37630 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  idden..**.** The
37640 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
37650 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
37660 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f   the function to
37670 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a   invoke when a.*
37680 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  * row is updated
37690 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
376a0 6c 65 74 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69  leted..** The fi
376b0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
376c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
376d0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
376e0 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
376f0 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74  to sqlite3_updat
37700 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65  e_hook()..** The
37710 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b   second callback
37720 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
37730 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45   of [SQLITE_INSE
37740 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c  RT], [SQLITE_DEL
37750 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  ETE],.** or [SQL
37760 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70  ITE_UPDATE], dep
37770 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70  ending on the op
37780 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75  eration that cau
37790 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  sed the callback
377a0 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  .** to be invoke
377b0 64 2e 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  d..** The third 
377c0 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d  and fourth argum
377d0 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ents to the call
377e0 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69  back contain poi
377f0 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20  nters to the.** 
37800 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62  database and tab
37810 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69  le name containi
37820 6e 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20  ng the affected 
37830 72 6f 77 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61  row..** The fina
37840 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d  l callback param
37850 65 74 65 72 20 69 73 20 74 68 65 20 72 6f 77 69  eter is the rowi
37860 64 20 6f 66 20 74 68 65 20 72 6f 77 2e 20 49 6e  d of the row. In
37870 20 74 68 65 20 63 61 73 65 20 6f 66 0a 2a 2a 20   the case of.** 
37880 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
37890 69 73 20 74 68 65 20 72 6f 77 69 64 20 61 66 74  is the rowid aft
378a0 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61  er the update ta
378b0 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a  kes place..**.**
378c0 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
378d0 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
378e0 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79  when internal sy
378f0 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a  stem tables are.
37900 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65  ** modified (i.e
37910 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20  . sqlite_master 
37920 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65  and sqlite_seque
37930 6e 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  nce)..**.** If a
37940 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  nother function 
37950 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72  was previously r
37960 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70  egistered, its p
37970 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  Arg value.** is 
37980 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
37990 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74  wise NULL is ret
379a0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  urned..**.** INV
379b0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
379c0 48 31 32 39 37 31 7d 20 54 68 65 20 5b 73 71 6c  H12971} The [sql
379d0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
379e0 28 44 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61  (D,F,P)] interfa
379f0 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61  ce causes the ca
37a00 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20  llback.**       
37a10 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f     function F to
37a20 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
37a30 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
37a40 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20   P whenever.**  
37a50 20 20 20 20 20 20 20 20 61 20 74 61 62 6c 65 20          a table 
37a60 72 6f 77 20 69 73 20 6d 6f 64 69 66 69 65 64 2c  row is modified,
37a70 20 69 6e 73 65 72 74 65 64 2c 20 6f 72 20 64 65   inserted, or de
37a80 6c 65 74 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20  leted on.**     
37a90 20 20 20 20 20 74 68 65 20 5b 64 61 74 61 62 61       the [databa
37aa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
37ab0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37 33 7d  ..**.** {H12973}
37ac0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70   The [sqlite3_up
37ad0 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29  date_hook(D,F,P)
37ae0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
37af0 72 6e 73 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  rns the value.**
37b00 20 20 20 20 20 20 20 20 20 20 6f 66 20 50 20 66            of P f
37b10 6f 72 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  or the previous 
37b20 63 61 6c 6c 20 6f 6e 20 74 68 65 20 73 61 6d 65  call on the same
37b30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37b40 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20  ction] D,.**    
37b50 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 66 6f        or NULL fo
37b60 72 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  r the first call
37b70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37 35 7d  ..**.** {H12975}
37b80 20 49 66 20 74 68 65 20 75 70 64 61 74 65 20 68   If the update h
37b90 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 46 20 69  ook callback F i
37ba0 6e 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  n [sqlite3_updat
37bb0 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 0a 2a  e_hook(D,F,P)].*
37bc0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 4e 55  *          is NU
37bd0 4c 4c 20 74 68 65 6e 20 74 68 65 20 6e 6f 20 75  LL then the no u
37be0 70 64 61 74 65 20 63 61 6c 6c 62 61 63 6b 73 20  pdate callbacks 
37bf0 61 72 65 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20  are made..**.** 
37c00 7b 48 31 32 39 37 37 7d 20 45 61 63 68 20 63 61  {H12977} Each ca
37c10 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 75  ll to [sqlite3_u
37c20 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50  pdate_hook(D,F,P
37c30 29 5d 20 6f 76 65 72 72 69 64 65 73 20 70 72 69  )] overrides pri
37c40 6f 72 20 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20  or calls.**     
37c50 20 20 20 20 20 74 6f 20 74 68 65 20 73 61 6d 65       to the same
37c60 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 20 74 68   interface on th
37c70 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
37c80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
37c90 2a 2a 0a 2a 2a 20 7b 48 31 32 39 37 39 7d 20 54  **.** {H12979} T
37ca0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 63  he update hook c
37cb0 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69  allback is not i
37cc0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65  nvoked when inte
37cd0 72 6e 61 6c 20 73 79 73 74 65 6d 0a 2a 2a 20 20  rnal system.**  
37ce0 20 20 20 20 20 20 20 20 74 61 62 6c 65 73 20 73          tables s
37cf0 75 63 68 20 61 73 20 73 71 6c 69 74 65 5f 6d 61  uch as sqlite_ma
37d00 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f  ster and sqlite_
37d10 73 65 71 75 65 6e 63 65 20 61 72 65 20 6d 6f 64  sequence are mod
37d20 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ified..**.** {H1
37d30 32 39 38 31 7d 20 54 68 65 20 73 65 63 6f 6e 64  2981} The second
37d40 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
37d50 65 20 75 70 64 61 74 65 20 63 61 6c 6c 62 61 63  e update callbac
37d60 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  k.**          is
37d70 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
37d80 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45  INSERT], [SQLITE
37d90 5f 44 45 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c  _DELETE] or [SQL
37da0 49 54 45 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20  ITE_UPDATE],.** 
37db0 20 20 20 20 20 20 20 20 20 64 65 70 65 6e 64 69           dependi
37dc0 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74  ng on the operat
37dd0 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20  ion that caused 
37de0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20  the callback to 
37df0 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  be invoked..**.*
37e00 2a 20 7b 48 31 32 39 38 33 7d 20 54 68 65 20 74  * {H12983} The t
37e10 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
37e20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
37e30 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
37e40 6e 20 70 6f 69 6e 74 65 72 73 0a 2a 2a 20 20 20  n pointers.**   
37e50 20 20 20 20 20 20 20 74 6f 20 7a 65 72 6f 2d 74         to zero-t
37e60 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
37e70 73 74 72 69 6e 67 73 20 77 68 69 63 68 20 61 72  strings which ar
37e80 65 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  e the names of t
37e90 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  he.**          d
37ea0 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c  atabase and tabl
37eb0 65 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  e that is being 
37ec0 75 70 64 61 74 65 64 2e 0a 0a 2a 2a 20 7b 48 31  updated...** {H1
37ed0 32 39 38 35 7d 20 54 68 65 20 66 69 6e 61 6c 20  2985} The final 
37ee0 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74  callback paramet
37ef0 65 72 20 69 73 20 74 68 65 20 72 6f 77 69 64 20  er is the rowid 
37f00 6f 66 20 74 68 65 20 72 6f 77 20 61 66 74 65 72  of the row after
37f10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
37f20 20 63 68 61 6e 67 65 20 6f 63 63 75 72 73 2e 0a   change occurs..
37f30 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
37f40 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20  _update_hook(.  
37f50 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
37f60 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20  d(*)(void *,int 
37f70 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68  ,char const *,ch
37f80 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74  ar const *,sqlit
37f90 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69  e3_int64),.  voi
37fa0 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  d*.);../*.** CAP
37fb0 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
37fc0 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20   Disable Shared 
37fd0 50 61 67 65 72 20 43 61 63 68 65 20 7b 48 31 30  Pager Cache {H10
37fe0 33 33 30 7d 20 3c 53 33 30 39 30 30 3e 0a 2a 2a  330} <S30900>.**
37ff0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72   KEYWORDS: {shar
38000 65 64 20 63 61 63 68 65 7d 20 7b 73 68 61 72 65  ed cache} {share
38010 64 20 63 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a  d cache mode}.**
38020 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
38030 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
38040 62 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67  bles the sharing
38050 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
38060 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63   cache.** and sc
38070 68 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74  hema data struct
38080 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61  ures between [da
38090 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
380a0 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  n | connections]
380b0 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20  .** to the same 
380c0 64 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e  database. Sharin
380d0 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  g is enabled if 
380e0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  the argument is 
380f0 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61  true.** and disa
38100 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75  bled if the argu
38110 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a  ment is false..*
38120 2a 0a 2a 2a 20 43 61 63 68 65 20 73 68 61 72 69  *.** Cache shari
38130 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e  ng is enabled an
38140 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61  d disabled for a
38150 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73  n entire process
38160 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 54 68 69 73 20  . {END}.** This 
38170 69 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f  is a change as o
38180 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
38190 20 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72   3.5.0. In prior
381a0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
381b0 69 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20  ite,.** sharing 
381c0 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  was enabled or d
381d0 69 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68  isabled for each
381e0 20 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65   thread separate
381f0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  ly..**.** The ca
38200 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65  che sharing mode
38210 20 73 65 74 20 62 79 20 74 68 69 73 20 69 6e 74   set by this int
38220 65 72 66 61 63 65 20 65 66 66 65 63 74 73 20 61  erface effects a
38230 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  ll subsequent.**
38240 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
38250 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
38260 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
38270 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70   and [sqlite3_op
38280 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73  en16()]..** Exis
38290 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f  ting database co
382a0 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e  nnections contin
382b0 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72 69  ue use the shari
382c0 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20  ng mode.** that 
382d0 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 61 74  was in effect at
382e0 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20 77   the time they w
382f0 65 72 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a  ere opened..**.*
38300 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73  * Virtual tables
38310 20 63 61 6e 6e 6f 74 20 62 65 20 75 73 65 64 20   cannot be used 
38320 77 69 74 68 20 61 20 73 68 61 72 65 64 20 63 61  with a shared ca
38330 63 68 65 2e 20 20 57 68 65 6e 20 73 68 61 72 65  che.  When share
38340 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
38350 61 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69  abled, the [sqli
38360 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
38370 65 28 29 5d 20 41 50 49 20 75 73 65 64 20 74 6f  e()] API used to
38380 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 72   register.** vir
38390 74 75 61 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c  tual tables will
383a0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61   always return a
383b0 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  n error..**.** T
383c0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
383d0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
383e0 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20  if shared cache 
383f0 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  was enabled or d
38400 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65  isabled.** succe
38410 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72  ssfully.  An [er
38420 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
38430 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e  urned otherwise.
38440 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63 61  .**.** Shared ca
38450 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  che is disabled 
38460 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20  by default. But 
38470 74 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67  this might chang
38480 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72  e in.** future r
38490 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
384a0 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  e.  Applications
384b0 20 74 68 61 74 20 63 61 72 65 20 61 62 6f 75 74   that care about
384c0 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
384d0 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20   setting should 
384e0 73 65 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c  set it explicitl
384f0 79 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  y..**.** INVARIA
38500 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 33  NTS:.**.** {H103
38510 33 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  31} A successful
38520 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
38530 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73  sqlite3_enable_s
38540 68 61 72 65 64 5f 63 61 63 68 65 28 42 29 5d 0a  hared_cache(B)].
38550 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 6c 6c  **          will
38560 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
38570 6c 65 20 73 68 61 72 65 64 20 63 61 63 68 65 20  le shared cache 
38580 6d 6f 64 65 20 66 6f 72 20 61 6e 79 20 73 75 62  mode for any sub
38590 73 65 71 75 65 6e 74 6c 79 0a 2a 2a 20 20 20 20  sequently.**    
385a0 20 20 20 20 20 20 63 72 65 61 74 65 64 20 5b 64        created [d
385b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
385c0 6f 6e 5d 20 69 6e 20 74 68 65 20 73 61 6d 65 20  on] in the same 
385d0 70 72 6f 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 7b  process..**.** {
385e0 48 31 30 33 33 36 7d 20 57 68 65 6e 20 73 68 61  H10336} When sha
385f0 72 65 64 20 63 61 63 68 65 20 69 73 20 65 6e 61  red cache is ena
38600 62 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74  bled, the [sqlit
38610 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
38620 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
38630 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 61  interface will a
38640 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20  lways return an 
38650 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  error..**.** {H1
38660 30 33 33 37 7d 20 54 68 65 20 5b 73 71 6c 69 74  0337} The [sqlit
38670 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
38680 5f 63 61 63 68 65 28 42 29 5d 20 69 6e 74 65 72  _cache(B)] inter
38690 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
386a0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
386b0 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63  _OK] if shared c
386c0 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64  ache was enabled
386d0 20 6f 72 20 64 69 73 61 62 6c 65 64 20 73 75 63   or disabled suc
386e0 63 65 73 73 66 75 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  cessfully..**.**
386f0 20 7b 48 31 30 33 33 39 7d 20 53 68 61 72 65 64   {H10339} Shared
38700 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c   cache is disabl
38710 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
38720 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
38730 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
38740 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e(int);../*.** C
38750 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74  API3REF: Attempt
38760 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65   To Free Heap Me
38770 6d 6f 72 79 20 7b 48 31 37 33 34 30 7d 20 3c 53  mory {H17340} <S
38780 33 30 32 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30220>.**.** The
38790 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
387a0 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66  _memory() interf
387b0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
387c0 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20  free N bytes.** 
387d0 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62  of heap memory b
387e0 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e  y deallocating n
387f0 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d  on-essential mem
38800 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a  ory allocations.
38810 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64  ** held by the d
38820 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e  atabase library.
38830 20 7b 45 4e 44 7d 20 20 4d 65 6d 6f 72 79 20 75   {END}  Memory u
38840 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74  sed to cache dat
38850 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74  abase.** pages t
38860 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  o improve perfor
38870 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d  mance is an exam
38880 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e  ple of non-essen
38890 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  tial memory..** 
388a0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
388b0 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73  memory() returns
388c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
388d0 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72  ytes actually fr
3