System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 3c0a2a4d1b97d67c71e6ce00ef0891b060a223c0:


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 33 2e 68 2c   $Id: sqlite3.h,
05e0: 76 20 31 2e 31 20 32 30 30 38 2f 30 38 2f 30 36  v 1.1 2008/08/06
05f0: 20 32 31 3a 34 38 3a 30 37 20 72 6d 73 69 6d 70   21:48:07 rmsimp
0600: 73 6f 6e 20 45 78 70 20 24 0a 2a 2f 0a 23 69 66  son Exp $.*/.#if
0610: 6e 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f  ndef _SQLITE3_H_
0620: 0a 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45  .#define _SQLITE
0630: 33 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73  3_H_.#include <s
0640: 74 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20  tdarg.h>     /* 
0650: 4e 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64  Needed for the d
0660: 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f  efinition of va_
0670: 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d  list */../*.** M
0680: 61 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20  ake sure we can 
0690: 63 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20  call this stuff 
06a0: 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66  from C++..*/.#if
06b0: 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a  def __cplusplus.
06c0: 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e  extern "C" {.#en
06d0: 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20  dif.../*.** Add 
06e0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06f0: 76 65 72 72 69 64 65 20 27 65 78 74 65 72 6e 27  verride 'extern'
0700: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
0710: 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69  TE_EXTERN.# defi
0720: 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  ne SQLITE_EXTERN
0730: 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a   extern.#endif..
0740: 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65  /*.** Ensure the
0750: 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20  se symbols were 
0760: 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20 73  not defined by s
0770: 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65 61  ome previous hea
0780: 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66  der file..*/.#if
0790: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
07a0: 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  ON.# undef SQLIT
07b0: 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66  E_VERSION.#endif
07c0: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56  .#ifdef SQLITE_V
07d0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20  ERSION_NUMBER.# 
07e0: 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  undef SQLITE_VER
07f0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64  SION_NUMBER.#end
0800: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
0810: 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
0820: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
0830: 20 4e 75 6d 62 65 72 73 20 7b 48 31 30 30 31 30   Numbers {H10010
0840: 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60100>.**.**
0850: 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53   The SQLITE_VERS
0860: 49 4f 4e 20 61 6e 64 20 53 51 4c 49 54 45 5f 56  ION and SQLITE_V
0870: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 64  ERSION_NUMBER #d
0880: 65 66 69 6e 65 73 20 69 6e 0a 2a 2a 20 74 68 65  efines in.** the
0890: 20 73 71 6c 69 74 65 33 2e 68 20 66 69 6c 65 20   sqlite3.h file 
08a0: 73 70 65 63 69 66 79 20 74 68 65 20 76 65 72 73  specify the vers
08b0: 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ion of SQLite wi
08c0: 74 68 20 77 68 69 63 68 0a 2a 2a 20 74 68 61 74  th which.** that
08d0: 20 68 65 61 64 65 72 20 66 69 6c 65 20 69 73 20   header file is 
08e0: 61 73 73 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a  associated..**.*
08f0: 2a 20 54 68 65 20 22 76 65 72 73 69 6f 6e 22 20  * The "version" 
0900: 6f 66 20 53 51 4c 69 74 65 20 69 73 20 61 20 73  of SQLite is a s
0910: 74 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6f 72  tring of the for
0920: 6d 20 22 58 2e 59 2e 5a 22 2e 0a 2a 2a 20 54 68  m "X.Y.Z"..** Th
0930: 65 20 70 68 72 61 73 65 20 22 61 6c 70 68 61 22  e phrase "alpha"
0940: 20 6f 72 20 22 62 65 74 61 22 20 6d 69 67 68 74   or "beta" might
0950: 20 62 65 20 61 70 70 65 6e 64 65 64 20 61 66 74   be appended aft
0960: 65 72 20 74 68 65 20 5a 2e 0a 2a 2a 20 54 68 65  er the Z..** The
0970: 20 58 20 76 61 6c 75 65 20 69 73 20 6d 61 6a 6f   X value is majo
0980: 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  r version number
0990: 20 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51 4c   always 3 in SQL
09a0: 69 74 65 33 2e 0a 2a 2a 20 54 68 65 20 58 20 76  ite3..** The X v
09b0: 61 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65  alue only change
09c0: 73 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64 73  s when backwards
09d0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69   compatibility i
09e0: 73 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 20  s.** broken and 
09f0: 77 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76  we intend to nev
0a00: 65 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61 72  er break backwar
0a10: 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
0a20: 2e 0a 2a 2a 20 54 68 65 20 59 20 76 61 6c 75 65  ..** The Y value
0a30: 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65   is the minor ve
0a40: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64  rsion number and
0a50: 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68   only changes wh
0a60: 65 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65 20  en.** there are 
0a70: 6d 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65 6e  major feature en
0a80: 68 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74 20  hancements that 
0a90: 61 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f 6d  are forwards com
0aa0: 70 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e  patible.** but n
0ab0: 6f 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ot backwards com
0ac0: 70 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20  patible..** The 
0ad0: 5a 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 72  Z value is the r
0ae0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61 6e  elease number an
0af0: 64 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64  d is incremented
0b00: 20 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 65   with.** each re
0b10: 6c 65 61 73 65 20 62 75 74 20 72 65 73 65 74 73  lease but resets
0b20: 20 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e 65   back to 0 whene
0b30: 76 65 72 20 59 20 69 73 20 69 6e 63 72 65 6d 65  ver Y is increme
0b40: 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  nted..**.** See 
0b50: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c  also: [sqlite3_l
0b60: 69 62 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64  ibversion()] and
0b70: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
0b80: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2e 0a  sion_number()]..
0b90: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
0ba0: 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 31 31 7d  :.**.** {H10011}
0bb0: 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53   The SQLITE_VERS
0bc0: 49 4f 4e 20 23 64 65 66 69 6e 65 20 69 6e 20 74  ION #define in t
0bd0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61  he sqlite3.h hea
0be0: 64 65 72 20 66 69 6c 65 20 73 68 61 6c 6c 0a 2a  der file shall.*
0bf0: 2a 20 20 20 20 20 20 20 20 20 20 65 76 61 6c 75  *          evalu
0c00: 61 74 65 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ate to a string 
0c10: 6c 69 74 65 72 61 6c 20 74 68 61 74 20 69 73 20  literal that is 
0c20: 74 68 65 20 53 51 4c 69 74 65 20 76 65 72 73 69  the SQLite versi
0c30: 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  on.**          w
0c40: 69 74 68 20 77 68 69 63 68 20 74 68 65 20 68 65  ith which the he
0c50: 61 64 65 72 20 66 69 6c 65 20 69 73 20 61 73 73  ader file is ass
0c60: 6f 63 69 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  ociated..**.** {
0c70: 48 31 30 30 31 34 7d 20 54 68 65 20 53 51 4c 49  H10014} The SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
0c90: 52 20 23 64 65 66 69 6e 65 20 73 68 61 6c 6c 20  R #define shall 
0ca0: 72 65 73 6f 6c 76 65 20 74 6f 20 61 6e 20 69 6e  resolve to an in
0cb0: 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  teger.**        
0cc0: 20 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65    with the value
0cd0: 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a   (X*1000000 + Y*
0ce0: 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20  1000 + Z) where 
0cf0: 58 2c 20 59 2c 20 61 6e 64 20 5a 0a 2a 2a 20 20  X, Y, and Z.**  
0d00: 20 20 20 20 20 20 20 20 61 72 65 20 74 68 65 20          are the 
0d10: 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 2c 20 6d  major version, m
0d20: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 2c 20 61 6e  inor version, an
0d30: 64 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72  d release number
0d40: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
0d50: 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20  ITE_VERSION     
0d60: 20 20 20 20 22 33 2e 36 2e 31 22 0a 23 64 65 66      "3.6.1".#def
0d70: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ine SQLITE_VERSI
0d80: 4f 4e 5f 4e 55 4d 42 45 52 20 20 33 30 30 36 30  ON_NUMBER  30060
0d90: 30 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  01../*.** CAPI3R
0da0: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
0db0: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
0dc0: 62 65 72 73 20 7b 48 31 30 30 32 30 7d 20 3c 53  bers {H10020} <S
0dd0: 36 30 31 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  60100>.** KEYWOR
0de0: 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73  DS: sqlite3_vers
0df0: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ion.**.** These 
0e00: 66 65 61 74 75 72 65 73 20 70 72 6f 76 69 64 65  features provide
0e10: 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
0e20: 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51  ation as the [SQ
0e30: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a  LITE_VERSION].**
0e40: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 56 45 52   and [SQLITE_VER
0e50: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 23 64 65  SION_NUMBER] #de
0e60: 66 69 6e 65 73 20 69 6e 20 74 68 65 20 68 65 61  fines in the hea
0e70: 64 65 72 2c 20 62 75 74 20 61 72 65 20 61 73 73  der, but are ass
0e80: 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
0e90: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74  the library inst
0ea0: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65  ead of the heade
0eb0: 72 20 66 69 6c 65 2e 20 20 43 61 75 74 69 6f 75  r file.  Cautiou
0ec0: 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  s programmers mi
0ed0: 67 68 74 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 61  ght.** include a
0ee0: 20 63 68 65 63 6b 20 69 6e 20 74 68 65 69 72 20   check in their 
0ef0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 76  application to v
0f00: 65 72 69 66 79 20 74 68 61 74 0a 2a 2a 20 73 71  erify that.** sq
0f10: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f20: 5f 6e 75 6d 62 65 72 28 29 20 61 6c 77 61 79 73  _number() always
0f30: 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
0f40: 75 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  ue.** [SQLITE_VE
0f50: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a 2a  RSION_NUMBER]..*
0f60: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75  _libversion() fu
0f80: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
0f90: 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
0fa0: 69 6f 6e 20 61 73 20 69 73 0a 2a 2a 20 69 6e 20  ion as is.** in 
0fb0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  the sqlite3_vers
0fc0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
0fd0: 73 74 61 6e 74 2e 20 20 54 68 65 20 66 75 6e 63  stant.  The func
0fe0: 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64  tion is provided
0ff0: 0a 2a 2a 20 66 6f 72 20 75 73 65 20 69 6e 20 44  .** for use in D
1000: 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73  LLs since DLL us
1010: 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e  ers usually do n
1020: 6f 74 20 68 61 76 65 20 64 69 72 65 63 74 20 61  ot have direct a
1030: 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 0a  ccess to string.
1040: 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74  ** constants wit
1050: 68 69 6e 20 74 68 65 20 44 4c 4c 2e 0a 2a 2a 0a  hin the DLL..**.
1060: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
1070: 2a 0a 2a 2a 20 7b 48 31 30 30 32 31 7d 20 54 68  *.** {H10021} Th
1080: 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  e [sqlite3_libve
1090: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 20  rsion_number()] 
10a0: 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
10b0: 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20  return.**       
10c0: 20 20 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71     an integer eq
10d0: 75 61 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 56  ual to [SQLITE_V
10e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 0a  ERSION_NUMBER]..
10f0: 2a 2a 0a 2a 2a 20 7b 48 31 30 30 32 32 7d 20 54  **.** {H10022} T
1100: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65 72 73  he [sqlite3_vers
1110: 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  ion] string cons
1120: 74 61 6e 74 20 73 68 61 6c 6c 20 63 6f 6e 74 61  tant shall conta
1130: 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  in.**          t
1140: 68 65 20 74 65 78 74 20 6f 66 20 74 68 65 20 5b  he text of the [
1150: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
1160: 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  string..**.** {H
1170: 31 30 30 32 33 7d 20 54 68 65 20 5b 73 71 6c 69  10023} The [sqli
1180: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
1190: 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c  ] function shall
11a0: 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20   return.**      
11b0: 20 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f      a pointer to
11c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 65   the [sqlite3_ve
11d0: 72 73 69 6f 6e 5d 20 73 74 72 69 6e 67 20 63 6f  rsion] string co
11e0: 6e 73 74 61 6e 74 2e 0a 2a 2f 0a 53 51 4c 49 54  nstant..*/.SQLIT
11f0: 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63  E_EXTERN const c
1200: 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73  har sqlite3_vers
1210: 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61  ion[];.const cha
1220: 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  r *sqlite3_libve
1230: 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 69 6e 74  rsion(void);.int
1240: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1250: 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29  ion_number(void)
1260: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1270: 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  F: Test To See I
1280: 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73  f The Library Is
1290: 20 54 68 72 65 61 64 73 61 66 65 20 7b 48 31 30   Threadsafe {H10
12a0: 31 30 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a  100} <S60100>.**
12b0: 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62  .** SQLite can b
12c0: 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  e compiled with 
12d0: 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78  or without mutex
12e0: 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65  es.  When.** the
12f0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1300: 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73  AFE] C preproces
1310: 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 74 72 75  sor macro is tru
1320: 65 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  e, mutexes.** ar
1330: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1340: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1350: 66 65 2e 20 20 57 68 65 6e 20 74 68 61 74 20 6d  fe.  When that m
1360: 61 63 72 6f 20 69 73 20 66 61 6c 73 65 2c 0a 2a  acro is false,.*
1370: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72  * the mutexes ar
1380: 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68  e omitted.  With
1390: 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c  out the mutexes,
13a0: 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a   it is not safe.
13b0: 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65  ** to use SQLite
13c0: 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72   concurrently fr
13d0: 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  om more than one
13e0: 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45   thread..**.** E
13f0: 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20  nabling mutexes 
1400: 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61  incurs a measura
1410: 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ble performance 
1420: 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69  penalty..** So i
1430: 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74  f speed is of ut
1440: 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c  most importance,
1450: 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20   it makes sense 
1460: 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68  to disable.** th
1470: 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20  e mutexes.  But 
1480: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65  for maximum safe
1490: 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75  ty, mutexes shou
14a0: 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a  ld be enabled..*
14b0: 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 62 65  * The default be
14c0: 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75  havior is for mu
14d0: 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62  texes to be enab
14e0: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  led..**.** This 
14f0: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
1500: 20 75 73 65 64 20 62 79 20 61 20 70 72 6f 67 72   used by a progr
1510: 61 6d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  am to make sure 
1520: 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73  that the.** vers
1530: 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68  ion of SQLite th
1540: 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67  at it is linking
1550: 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d   against was com
1560: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
1570: 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69 6e  e desired settin
1580: 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  g of the [SQLITE
1590: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63  _THREADSAFE] mac
15a0: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ro..**.** This i
15b0: 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65  nterface only re
15c0: 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d  ports on the com
15d0: 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20  pile-time mutex 
15e0: 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68  setting.** of th
15f0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
1600: 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20  SAFE] flag.  If 
1610: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
1620: 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54  ed with.** SQLIT
1630: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 74  E_THREADSAFE=1 t
1640: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20  hen mutexes are 
1650: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
1660: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65  lt but.** can be
1670: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61   fully or partia
1680: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69  lly disabled usi
1690: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
16a0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a  lite3_config()].
16b0: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62  ** with the verb
16c0: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  s [SQLITE_CONFIG
16d0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20  _SINGLETHREAD], 
16e0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
16f0: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20  ULTITHREAD],.** 
1700: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
1710: 47 5f 4d 55 54 45 58 5d 2e 20 20 54 68 65 20 72  G_MUTEX].  The r
1720: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
1730: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  his function sho
1740: 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20 64  ws.** only the d
1750: 65 66 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d 74  efault compile-t
1760: 69 6d 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f 74  ime setting, not
1770: 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68   any run-time ch
1780: 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61 74  anges.** to that
1790: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
17a0: 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
17b0: 2a 20 7b 48 31 30 31 30 31 7d 20 54 68 65 20 5b  * {H10101} The [
17c0: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
17d0: 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73  fe()] function s
17e0: 68 61 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 7a  hall return nonz
17f0: 65 72 6f 20 69 66 0a 2a 2a 20 20 20 20 20 20 20  ero if.**       
1800: 20 20 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f     SQLite was co
1810: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
1820: 69 74 73 20 6d 75 74 65 78 65 73 20 65 6e 61 62  its mutexes enab
1830: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 0a 2a  led by default.*
1840: 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 7a 65  *          or ze
1850: 72 6f 20 69 66 20 53 51 4c 69 74 65 20 77 61 73  ro if SQLite was
1860: 20 63 6f 6d 70 69 6c 65 64 20 73 75 63 68 20 74   compiled such t
1870: 68 61 74 20 6d 75 74 65 78 65 73 20 61 72 65 0a  hat mutexes are.
1880: 2a 2a 20 20 20 20 20 20 20 20 20 20 70 65 72 6d  **          perm
1890: 61 6e 65 6e 74 6c 79 20 64 69 73 61 62 6c 65 64  anently disabled
18a0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 31 30 32 7d  ..**.** {H10102}
18b0: 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   The value retur
18c0: 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ned by the [sqli
18d0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
18e0: 5d 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  ] function.**   
18f0: 20 20 20 20 20 20 20 73 68 61 6c 6c 20 6e 6f 74         shall not
1900: 20 63 68 61 6e 67 65 20 77 68 65 6e 20 6d 75 74   change when mut
1910: 65 78 20 73 65 74 74 69 6e 67 20 61 72 65 20 6d  ex setting are m
1920: 6f 64 69 66 69 65 64 20 61 74 0a 2a 2a 20 20 20  odified at.**   
1930: 20 20 20 20 20 20 20 72 75 6e 74 69 6d 65 20 75         runtime u
1940: 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  sing the [sqlite
1950: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
1960: 72 66 61 63 65 20 61 6e 64 20 0a 2a 2a 20 20 20  rface and .**   
1970: 20 20 20 20 20 20 20 65 73 70 65 63 69 61 6c 6c         especiall
1980: 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  y the [SQLITE_CO
1990: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
19a0: 44 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  D],.**          
19b0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
19c0: 55 4c 54 49 54 48 52 45 41 44 5d 2c 20 5b 53 51  ULTITHREAD], [SQ
19d0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
19e0: 41 4c 49 5a 45 44 5d 2c 0a 2a 2a 20 20 20 20 20  ALIZED],.**     
19f0: 20 20 20 20 20 61 6e 64 20 5b 53 51 4c 49 54 45       and [SQLITE
1a00: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20 76  _CONFIG_MUTEX] v
1a10: 65 72 62 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  erbs..*/.int sql
1a20: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
1a30: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
1a40: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
1a50: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
1a60: 6c 65 20 7b 48 31 32 30 30 30 7d 20 3c 53 34 30  le {H12000} <S40
1a70: 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  200>.** KEYWORDS
1a80: 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  : {database conn
1a90: 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73  ection} {databas
1aa0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a  e connections}.*
1ab0: 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53  *.** Each open S
1ac0: 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69  QLite database i
1ad0: 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  s represented by
1ae0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
1af0: 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20   instance of.** 
1b00: 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63  the opaque struc
1b10: 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69  ture named "sqli
1b20: 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65  te3".  It is use
1b30: 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20  ful to think of 
1b40: 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f  an sqlite3.** po
1b50: 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65  inter as an obje
1b60: 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ct.  The [sqlite
1b70: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1b80: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61  te3_open16()], a
1b90: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  nd.** [sqlite3_o
1ba0: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
1bb0: 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e  aces are its con
1bc0: 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b  structors, and [
1bd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
1be0: 0a 2a 2a 20 69 73 20 69 74 73 20 64 65 73 74 72  .** is its destr
1bf0: 75 63 74 6f 72 2e 20 20 54 68 65 72 65 20 61 72  uctor.  There ar
1c00: 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 69 6e 74  e many other int
1c10: 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73  erfaces (such as
1c20: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1c30: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
1c40: 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
1c50: 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  tion()], and.** 
1c60: 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
1c70: 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65  meout()] to name
1c80: 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74   but three) that
1c90: 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20   are methods on 
1ca0: 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62  an.** sqlite3 ob
1cb0: 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ject..*/.typedef
1cc0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20   struct sqlite3 
1cd0: 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20  sqlite3;../*.** 
1ce0: 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74  CAPI3REF: 64-Bit
1cf0: 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 20 7b   Integer Types {
1d00: 48 31 30 32 30 30 7d 20 3c 53 31 30 31 31 30 3e  H10200} <S10110>
1d10: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1d20: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74  lite_int64 sqlit
1d30: 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42  e_uint64.**.** B
1d40: 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20  ecause there is 
1d50: 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72  no cross-platfor
1d60: 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79  m way to specify
1d70: 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
1d80: 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20  types.** SQLite 
1d90: 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66  includes typedef
1da0: 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67  s for 64-bit sig
1db0: 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64  ned and unsigned
1dc0: 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a   integers..**.**
1dd0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   The sqlite3_int
1de0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75  64 and sqlite3_u
1df0: 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72  int64 are the pr
1e00: 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66  eferred type def
1e10: 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65  initions..** The
1e20: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e   sqlite_int64 an
1e30: 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20  d sqlite_uint64 
1e40: 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72  types are suppor
1e50: 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ted for backward
1e60: 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69  s.** compatibili
1e70: 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 49  ty only..**.** I
1e80: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
1e90: 20 7b 48 31 30 32 30 31 7d 20 54 68 65 20 5b 73   {H10201} The [s
1ea0: 71 6c 69 74 65 5f 69 6e 74 36 34 5d 20 61 6e 64  qlite_int64] and
1eb0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 5d   [sqlite3_int64]
1ec0: 20 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63   type shall spec
1ed0: 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ify.**          
1ee0: 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  a 64-bit signed 
1ef0: 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  integer..**.** {
1f00: 48 31 30 32 30 32 7d 20 54 68 65 20 5b 73 71 6c  H10202} The [sql
1f10: 69 74 65 5f 75 69 6e 74 36 34 5d 20 61 6e 64 20  ite_uint64] and 
1f20: 5b 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 5d  [sqlite3_uint64]
1f30: 20 74 79 70 65 20 73 68 61 6c 6c 20 73 70 65 63   type shall spec
1f40: 69 66 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ify.**          
1f50: 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65  a 64-bit unsigne
1f60: 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2f 0a 23 69  d integer..*/.#i
1f70: 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  fdef SQLITE_INT6
1f80: 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66  4_TYPE.  typedef
1f90: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
1fa0: 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  PE sqlite_int64;
1fb0: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
1fc0: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  ned SQLITE_INT64
1fd0: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e  _TYPE sqlite_uin
1fe0: 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e  t64;.#elif defin
1ff0: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20  ed(_MSC_VER) || 
2000: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e  defined(__BORLAN
2010: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20  DC__).  typedef 
2020: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69  __int64 sqlite_i
2030: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
2040: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34  unsigned __int64
2050: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2060: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20  #else.  typedef 
2070: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
2080: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
2090: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c  pedef unsigned l
20a0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
20b0: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64  ite_uint64;.#end
20c0: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  if.typedef sqlit
20d0: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  e_int64 sqlite3_
20e0: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73  int64;.typedef s
20f0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c  qlite_uint64 sql
2100: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a  ite3_uint64;../*
2110: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67  .** If compiling
2120: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72   for a processor
2130: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61   that lacks floa
2140: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f  ting point suppo
2150: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74  rt,.** substitut
2160: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c  e integer for fl
2170: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f  oating-point..*/
2180: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f  .#ifdef SQLITE_O
2190: 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49  MIT_FLOATING_POI
21a0: 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62  NT.# define doub
21b0: 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  le sqlite3_int64
21c0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
21d0: 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67  API3REF: Closing
21e0: 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e   A Database Conn
21f0: 65 63 74 69 6f 6e 20 7b 48 31 32 30 31 30 7d 20  ection {H12010} 
2200: 3c 53 33 30 31 30 30 3e 3c 53 34 30 32 30 30 3e  <S30100><S40200>
2210: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2220: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2230: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2240: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2250: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
2260: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74  ns should [sqlit
2270: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
2280: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65  nalize] all [pre
2290: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
22a0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
22b0: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63  3_blob_close | c
22c0: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20  lose] all [BLOB 
22d0: 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61  handles] associa
22e0: 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  ted with.** the 
22f0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2300: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
2310: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
2320: 65 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 65  e object..** The
2330: 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2340: 74 6d 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tmt()] interface
2350: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2360: 6c 6f 63 61 74 65 20 61 6c 6c 0a 2a 2a 20 5b 70  locate all.** [p
2370: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2380: 74 73 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77  ts] associated w
2390: 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
23a0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 66 20 64  connection] if d
23b0: 65 73 69 72 65 64 2e 0a 2a 2a 20 54 79 70 69 63  esired..** Typic
23c0: 61 6c 20 63 6f 64 65 20 6d 69 67 68 74 20 6c 6f  al code might lo
23d0: 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ok like this:.**
23e0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
23f0: 3c 70 72 65 3e 0a 2a 2a 20 73 71 6c 69 74 65 33  <pre>.** sqlite3
2400: 5f 73 74 6d 74 20 2a 70 53 74 6d 74 3b 0a 2a 2a  _stmt *pStmt;.**
2410: 20 77 68 69 6c 65 28 20 28 70 53 74 6d 74 20 3d   while( (pStmt =
2420: 20 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74   sqlite3_next_st
2430: 6d 74 28 64 62 2c 20 30 29 29 21 3d 30 20 29 7b  mt(db, 0))!=0 ){
2440: 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 73 71 6c  .** &nbsp;   sql
2450: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 70 53  ite3_finalize(pS
2460: 74 6d 74 29 3b 0a 2a 2a 20 7d 0a 2a 2a 20 3c 2f  tmt);.** }.** </
2470: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2480: 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  >.**.** If [sqli
2490: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20  te3_close()] is 
24a0: 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20  invoked while a 
24b0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
24c0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
24d0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
24e0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
24f0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  back..**.** INVA
2500: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
2510: 31 32 30 31 31 7d 20 41 20 73 75 63 63 65 73 73  12011} A success
2520: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
2530: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 73  ite3_close(C)] s
2540: 68 61 6c 6c 20 64 65 73 74 72 6f 79 20 74 68 65  hall destroy the
2550: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
2560: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2570: 6e 5d 20 6f 62 6a 65 63 74 20 43 2e 0a 2a 2a 0a  n] object C..**.
2580: 2a 2a 20 7b 48 31 32 30 31 32 7d 20 41 20 73 75  ** {H12012} A su
2590: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
25a0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
25b0: 43 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  C)] shall return
25c0: 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a   SQLITE_OK..**.*
25d0: 2a 20 7b 48 31 32 30 31 33 7d 20 41 20 73 75 63  * {H12013} A suc
25e0: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
25f0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
2600: 29 5d 20 73 68 61 6c 6c 20 72 65 6c 65 61 73 65  )] shall release
2610: 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20   all.**         
2620: 20 6d 65 6d 6f 72 79 20 61 6e 64 20 73 79 73 74   memory and syst
2630: 65 6d 20 72 65 73 6f 75 72 63 65 73 20 61 73 73  em resources ass
2640: 6f 63 69 61 74 65 64 20 77 69 74 68 20 5b 64 61  ociated with [da
2650: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2660: 6e 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43  n].**          C
2670: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 34 7d  ..**.** {H12014}
2680: 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   A call to [sqli
2690: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6f 6e  te3_close(C)] on
26a0: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
26b0: 6e 65 63 74 69 6f 6e 5d 20 43 20 74 68 61 74 0a  nection] C that.
26c0: 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 73 20  **          has 
26d0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 70 65 6e  one or more open
26e0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26f0: 6d 65 6e 74 73 5d 20 73 68 61 6c 6c 20 66 61 69  ments] shall fai
2700: 6c 20 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20  l with.**       
2710: 20 20 20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55     an [SQLITE_BU
2720: 53 59 5d 20 65 72 72 6f 72 20 63 6f 64 65 2e 0a  SY] error code..
2730: 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 35 7d 20 41  **.** {H12015} A
2740: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2750: 33 5f 63 6c 6f 73 65 28 43 29 5d 20 77 68 65 72  3_close(C)] wher
2760: 65 20 43 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  e C is a NULL po
2770: 69 6e 74 65 72 20 73 68 61 6c 6c 0a 2a 2a 20 20  inter shall.**  
2780: 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 53          return S
2790: 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20  QLITE_OK..**.** 
27a0: 7b 48 31 32 30 31 39 7d 20 57 68 65 6e 20 5b 73  {H12019} When [s
27b0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d  qlite3_close(C)]
27c0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61   is invoked on a
27d0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
27e0: 63 74 69 6f 6e 5d 20 43 0a 2a 2a 20 20 20 20 20  ction] C.**     
27f0: 20 20 20 20 20 74 68 61 74 20 68 61 73 20 61 20       that has a 
2800: 70 65 6e 64 69 6e 67 20 74 72 61 6e 73 61 63 74  pending transact
2810: 69 6f 6e 2c 20 74 68 65 20 74 72 61 6e 73 61 63  ion, the transac
2820: 74 69 6f 6e 20 73 68 61 6c 6c 20 62 65 0a 2a 2a  tion shall be.**
2830: 20 20 20 20 20 20 20 20 20 20 72 6f 6c 6c 65 64            rolled
2840: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 41 53 53   back..**.** ASS
2850: 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  UMPTIONS:.**.** 
2860: 7b 41 31 32 30 31 36 7d 20 54 68 65 20 43 20 70  {A12016} The C p
2870: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
2880: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d  ite3_close(C)] m
2890: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
28a0: 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  NULL.**         
28b0: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b   pointer or an [
28c0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
28d0: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64  pointer obtained
28e0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f  .**          fro
28f0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
2900: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2910: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20  n16()], or.**   
2920: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
2930: 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
2940: 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63  not previously c
2950: 6c 6f 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  losed..*/.int sq
2960: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69  lite3_close(sqli
2970: 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54  te3 *);../*.** T
2980: 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61  he type for a ca
2990: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e  llback function.
29a0: 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61  .** This is lega
29b0: 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65  cy and deprecate
29c0: 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64  d.  It is includ
29d0: 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  ed for historica
29e0: 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69  l.** compatibili
29f0: 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f  ty and is not do
2a00: 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70  cumented..*/.typ
2a10: 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74  edef int (*sqlit
2a20: 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69  e3_callback)(voi
2a30: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63  d*,int,char**, c
2a40: 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  har**);../*.** C
2a50: 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65  API3REF: One-Ste
2a60: 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f  p Query Executio
2a70: 6e 20 49 6e 74 65 72 66 61 63 65 20 7b 48 31 32  n Interface {H12
2a80: 31 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a  100} <S10000>.**
2a90: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2aa0: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65  exec() interface
2ab0: 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 74   is a convenient
2ac0: 20 77 61 79 20 6f 66 20 72 75 6e 6e 69 6e 67 20   way of running 
2ad0: 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 53  one or more.** S
2ae0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 77 69  QL statements wi
2af0: 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20  thout having to 
2b00: 77 72 69 74 65 20 61 20 6c 6f 74 20 6f 66 20 43  write a lot of C
2b10: 20 63 6f 64 65 2e 20 20 54 68 65 20 55 54 46 2d   code.  The UTF-
2b20: 38 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 53 51 4c  8 encoded.** SQL
2b30: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
2b40: 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
2b50: 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2b60: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
2b70: 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 74 61 74  c()..** The stat
2b80: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75  ements are evalu
2b90: 61 74 65 64 20 6f 6e 65 20 62 79 20 6f 6e 65 20  ated one by one 
2ba0: 75 6e 74 69 6c 20 65 69 74 68 65 72 20 61 6e 20  until either an 
2bb0: 65 72 72 6f 72 20 6f 72 0a 2a 2a 20 61 6e 20 69  error or.** an i
2bc0: 6e 74 65 72 72 75 70 74 20 69 73 20 65 6e 63 6f  nterrupt is enco
2bd0: 75 6e 74 65 72 65 64 2c 20 6f 72 20 75 6e 74 69  untered, or unti
2be0: 6c 20 74 68 65 79 20 61 72 65 20 61 6c 6c 20 64  l they are all d
2bf0: 6f 6e 65 2e 20 20 54 68 65 20 33 72 64 20 70 61  one.  The 3rd pa
2c00: 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 61 6e  rameter.** is an
2c10: 20 6f 70 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61   optional callba
2c20: 63 6b 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ck that is invok
2c30: 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
2c40: 20 72 6f 77 20 6f 66 20 61 6e 79 20 71 75 65 72   row of any quer
2c50: 79 0a 2a 2a 20 72 65 73 75 6c 74 73 20 70 72 6f  y.** results pro
2c60: 64 75 63 65 64 20 62 79 20 74 68 65 20 53 51 4c  duced by the SQL
2c70: 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68   statements.  Th
2c80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
2c90: 74 65 6c 6c 73 20 77 68 65 72 65 0a 2a 2a 20 74  tells where.** t
2ca0: 6f 20 77 72 69 74 65 20 61 6e 79 20 65 72 72 6f  o write any erro
2cb0: 72 20 6d 65 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a  r messages..**.*
2cc0: 2a 20 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * The error mess
2cd0: 61 67 65 20 70 61 73 73 65 64 20 62 61 63 6b 20  age passed back 
2ce0: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
2cf0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 68 65 6c  parameter is hel
2d00: 64 0a 2a 2a 20 69 6e 20 6d 65 6d 6f 72 79 20 6f  d.** in memory o
2d10: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2d20: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
2d30: 20 20 54 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d    To avoid a mem
2d40: 6f 72 79 20 6c 65 61 6b 2c 0a 2a 2a 20 74 68 65  ory leak,.** the
2d50: 20 63 61 6c 6c 69 6e 67 20 61 70 70 6c 69 63 61   calling applica
2d60: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 63 61 6c 6c  tion should call
2d70: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
2d80: 5d 20 6f 6e 20 61 6e 79 20 65 72 72 6f 72 0a 2a  ] on any error.*
2d90: 2a 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e  * message return
2da0: 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ed through the 5
2db0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 77 68 65  th parameter whe
2dc0: 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
2dd0: 64 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 65  d using.** the e
2de0: 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
2df0: 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
2e00: 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20  tatement in the 
2e10: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  2nd parameter is
2e20: 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74   NULL or an empt
2e30: 79 20 73 74 72 69 6e 67 0a 2a 2a 20 6f 72 20 61  y string.** or a
2e40: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
2e50: 6e 67 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ng only whitespa
2e60: 63 65 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 2c  ce and comments,
2e70: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 0a 2a 2a 20   then no SQL.** 
2e80: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65  statements are e
2e90: 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65  valuated and the
2ea0: 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74   database is not
2eb0: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
2ec0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
2ed0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2ee0: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 74  implemented in t
2ef0: 65 72 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  erms of.** [sqli
2f00: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2f10: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
2f20: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
2f30: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
2f40: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78  * The sqlite3_ex
2f50: 65 63 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  ec() routine doe
2f60: 73 20 6e 6f 74 68 69 6e 67 20 74 6f 20 74 68 65  s nothing to the
2f70: 20 64 61 74 61 62 61 73 65 20 74 68 61 74 20 63   database that c
2f80: 61 6e 6e 6f 74 20 62 65 20 64 6f 6e 65 0a 2a 2a  annot be done.**
2f90: 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
2fa0: 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  pare_v2()], [sql
2fb0: 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e  ite3_step()], an
2fc0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
2fd0: 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e  ize()]..**.** IN
2fe0: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
2ff0: 7b 48 31 32 31 30 31 7d 20 41 20 73 75 63 63 65  {H12101} A succe
3000: 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
3010: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   of [sqlite3_exe
3020: 63 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 0a 2a 2a  c(D,S,C,A,E)].**
3030: 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
3040: 73 65 71 75 65 6e 74 69 61 6c 6c 79 20 65 76 61  sequentially eva
3050: 6c 75 61 74 65 20 61 6c 6c 20 6f 66 20 74 68 65  luate all of the
3060: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
3070: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 65 6d 69  **          semi
3080: 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
3090: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
30a0: 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
30b0: 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
30c0: 20 20 73 74 72 69 6e 67 20 53 20 77 69 74 68 69    string S withi
30d0: 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66  n the context of
30e0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
30f0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a  onnection] D..**
3100: 0a 2a 2a 20 7b 48 31 32 31 30 32 7d 20 49 66 20  .** {H12102} If 
3110: 74 68 65 20 53 20 70 61 72 61 6d 65 74 65 72 20  the S parameter 
3120: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
3130: 28 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73 20  (D,S,C,A,E)] is 
3140: 4e 55 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20  NULL then.**    
3150: 20 20 20 20 20 20 74 68 65 20 61 63 74 69 6f 6e        the action
3160: 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61  s of the interfa
3170: 63 65 20 73 68 61 6c 6c 20 62 65 20 74 68 65 20  ce shall be the 
3180: 73 61 6d 65 20 61 73 20 69 66 20 74 68 65 0a 2a  same as if the.*
3190: 2a 20 20 20 20 20 20 20 20 20 20 53 20 70 61 72  *          S par
31a0: 61 6d 65 74 65 72 20 77 65 72 65 20 61 6e 20 65  ameter were an e
31b0: 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  mpty string..**.
31c0: 2a 2a 20 7b 48 31 32 31 30 34 7d 20 54 68 65 20  ** {H12104} The 
31d0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
31e0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
31f0: 20 73 68 61 6c 6c 20 62 65 20 5b 53 51 4c 49 54   shall be [SQLIT
3200: 45 5f 4f 4b 5d 20 69 66 20 61 6c 6c 0a 2a 2a 20  E_OK] if all.** 
3210: 20 20 20 20 20 20 20 20 20 53 51 4c 20 73 74 61           SQL sta
3220: 74 65 6d 65 6e 74 73 20 72 75 6e 20 73 75 63 63  tements run succ
3230: 65 73 73 66 75 6c 6c 79 20 61 6e 64 20 74 6f 20  essfully and to 
3240: 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
3250: 2a 20 7b 48 31 32 31 30 35 7d 20 54 68 65 20 72  * {H12105} The r
3260: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b  eturn value of [
3270: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3280: 73 68 61 6c 6c 20 62 65 20 61 6e 20 61 70 70 72  shall be an appr
3290: 6f 70 72 69 61 74 65 0a 2a 2a 20 20 20 20 20 20  opriate.**      
32a0: 20 20 20 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72      non-zero [er
32b0: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
32c0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
32d0: 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ails..**.** {H12
32e0: 31 30 37 7d 20 49 66 20 6f 6e 65 20 6f 72 20 6d  107} If one or m
32f0: 6f 72 65 20 6f 66 20 74 68 65 20 53 51 4c 20 73  ore of the SQL s
3300: 74 61 74 65 6d 65 6e 74 73 20 68 61 6e 64 65 64  tatements handed
3310: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65   to [sqlite3_exe
3320: 63 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  c()].**         
3330: 20 72 65 74 75 72 6e 20 72 65 73 75 6c 74 73 20   return results 
3340: 61 6e 64 20 74 68 65 20 33 72 64 20 70 61 72 61  and the 3rd para
3350: 6d 65 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  meter is not NUL
3360: 4c 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  L, then.**      
3370: 20 20 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b      the callback
3380: 20 66 75 6e 63 74 69 6f 6e 20 73 70 65 63 69 66   function specif
3390: 69 65 64 20 62 79 20 74 68 65 20 33 72 64 20 70  ied by the 3rd p
33a0: 61 72 61 6d 65 74 65 72 20 73 68 61 6c 6c 20 62  arameter shall b
33b0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  e.**          in
33c0: 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65  voked once for e
33d0: 61 63 68 20 72 6f 77 20 6f 66 20 72 65 73 75 6c  ach row of resul
33e0: 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 30  t..**.** {H12110
33f0: 7d 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63  } If the callbac
3400: 6b 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  k returns a non-
3410: 7a 65 72 6f 20 76 61 6c 75 65 20 74 68 65 6e 20  zero value then 
3420: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3430: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61  .**          sha
3440: 6c 6c 20 61 62 6f 72 74 20 74 68 65 20 53 51 4c  ll abort the SQL
3450: 20 73 74 61 74 65 6d 65 6e 74 20 69 74 20 69 73   statement it is
3460: 20 63 75 72 72 65 6e 74 6c 79 20 65 76 61 6c 75   currently evalu
3470: 61 74 69 6e 67 2c 0a 2a 2a 20 20 20 20 20 20 20  ating,.**       
3480: 20 20 20 73 6b 69 70 20 61 6c 6c 20 73 75 62 73     skip all subs
3490: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
34a0: 6d 65 6e 74 73 2c 20 61 6e 64 20 72 65 74 75 72  ments, and retur
34b0: 6e 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  n [SQLITE_ABORT]
34c0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 33 7d  ..**.** {H12113}
34d0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78   The [sqlite3_ex
34e0: 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68  ec()] routine sh
34f0: 61 6c 6c 20 70 61 73 73 20 69 74 73 20 34 74 68  all pass its 4th
3500: 20 70 61 72 61 6d 65 74 65 72 20 74 68 72 6f 75   parameter throu
3510: 67 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  gh.**          a
3520: 73 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  s the 1st parame
3530: 74 65 72 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ter of the callb
3540: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31  ack..**.** {H121
3550: 31 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  16} The [sqlite3
3560: 5f 65 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65  _exec()] routine
3570: 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 32   shall set the 2
3580: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
3590: 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  its.**          
35a0: 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 74  callback to be t
35b0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
35c0: 75 6d 6e 73 20 69 6e 20 74 68 65 20 63 75 72 72  umns in the curr
35d0: 65 6e 74 20 72 6f 77 20 6f 66 0a 2a 2a 20 20 20  ent row of.**   
35e0: 20 20 20 20 20 20 20 72 65 73 75 6c 74 2e 0a 2a         result..*
35f0: 2a 0a 2a 2a 20 7b 48 31 32 31 31 39 7d 20 54 68  *.** {H12119} Th
3600: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  e [sqlite3_exec(
3610: 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c  )] routine shall
3620: 20 73 65 74 20 74 68 65 20 33 72 64 20 70 61 72   set the 3rd par
3630: 61 6d 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a  ameter of its.**
3640: 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
3650: 63 6b 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61  ck to be an arra
3660: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
3670: 20 73 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67   strings holding
3680: 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
3690: 20 76 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68   values for each
36a0: 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63   column in the c
36b0: 75 72 72 65 6e 74 20 72 65 73 75 6c 74 20 73 65  urrent result se
36c0: 74 20 72 6f 77 20 61 73 0a 2a 2a 20 20 20 20 20  t row as.**     
36d0: 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72       obtained fr
36e0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
36f0: 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
3700: 2a 20 7b 48 31 32 31 32 32 7d 20 54 68 65 20 5b  * {H12122} The [
3710: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3720: 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65  routine shall se
3730: 74 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  t the 4th parame
3740: 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20  ter of its.**   
3750: 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20         callback 
3760: 74 6f 20 62 65 20 61 6e 20 61 72 72 61 79 20 6f  to be an array o
3770: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  f pointers to st
3780: 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68  rings holding th
3790: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61  e.**          na
37a0: 6d 65 73 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  mes of result co
37b0: 6c 75 6d 6e 73 20 61 73 20 6f 62 74 61 69 6e 65  lumns as obtaine
37c0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
37d0: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
37e0: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 32 35 7d 20 49  **.** {H12125} I
37f0: 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
3800: 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
3810: 65 78 65 63 28 29 5d 20 69 73 20 4e 55 4c 4c 20  exec()] is NULL 
3820: 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
3830: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3840: 5d 20 73 68 61 6c 6c 20 73 69 6c 65 6e 74 6c 79  ] shall silently
3850: 20 64 69 73 63 61 72 64 20 71 75 65 72 79 20 72   discard query r
3860: 65 73 75 6c 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  esults..**.** {H
3870: 31 32 31 33 31 7d 20 49 66 20 61 6e 20 65 72 72  12131} If an err
3880: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20  or occurs while 
3890: 70 61 72 73 69 6e 67 20 6f 72 20 65 76 61 6c 75  parsing or evalu
38a0: 61 74 69 6e 67 20 61 6e 79 20 6f 66 20 74 68 65  ating any of the
38b0: 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20   SQL.**         
38c0: 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
38d0: 68 65 20 53 20 70 61 72 61 6d 65 74 65 72 20 6f  he S parameter o
38e0: 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  f [sqlite3_exec(
38f0: 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 61 6e 64 20  D,S,C,A,E)] and 
3900: 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  if.**          t
3910: 68 65 20 45 20 70 61 72 61 6d 65 74 65 72 20 69  he E parameter i
3920: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
3930: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
3940: 5d 20 73 68 61 6c 6c 20 73 74 6f 72 65 0a 2a 2a  ] shall store.**
3950: 20 20 20 20 20 20 20 20 20 20 69 6e 20 2a 45 20            in *E 
3960: 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65  an appropriate e
3970: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 77 72 69  rror message wri
3980: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
3990: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 20 20 20   obtained.**    
39a0: 20 20 20 20 20 20 66 72 6f 6d 20 5b 73 71 6c 69        from [sqli
39b0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
39c0: 2a 0a 2a 2a 20 7b 48 31 32 31 33 34 7d 20 54 68  *.** {H12134} Th
39d0: 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  e [sqlite3_exec(
39e0: 44 2c 53 2c 43 2c 41 2c 45 29 5d 20 72 6f 75 74  D,S,C,A,E)] rout
39f0: 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68  ine shall set th
3a00: 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20  e value of.**   
3a10: 20 20 20 20 20 20 20 2a 45 20 74 6f 20 4e 55 4c         *E to NUL
3a20: 4c 20 69 66 20 45 20 69 73 20 6e 6f 74 20 4e 55  L if E is not NU
3a30: 4c 4c 20 61 6e 64 20 74 68 65 72 65 20 61 72 65  LL and there are
3a40: 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a   no errors..**.*
3a50: 2a 20 7b 48 31 32 31 33 37 7d 20 54 68 65 20 5b  * {H12137} The [
3a60: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53  sqlite3_exec(D,S
3a70: 2c 43 2c 41 2c 45 29 5d 20 66 75 6e 63 74 69 6f  ,C,A,E)] functio
3a80: 6e 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20  n shall set the 
3a90: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20  [error code].** 
3aa0: 20 20 20 20 20 20 20 20 20 61 6e 64 20 6d 65 73           and mes
3ab0: 73 61 67 65 20 61 63 63 65 73 73 69 62 6c 65 20  sage accessible 
3ac0: 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  via [sqlite3_err
3ad0: 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  code()],.**     
3ae0: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72       [sqlite3_er
3af0: 72 6d 73 67 28 29 5d 2c 20 61 6e 64 20 5b 73 71  rmsg()], and [sq
3b00: 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
3b10: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 33 38  ]..**.** {H12138
3b20: 7d 20 49 66 20 74 68 65 20 53 20 70 61 72 61 6d  } If the S param
3b30: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3b40: 5f 65 78 65 63 28 44 2c 53 2c 43 2c 41 2c 45 29  _exec(D,S,C,A,E)
3b50: 5d 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 0a  ] is NULL or an.
3b60: 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6d 70 74  **          empt
3b70: 79 20 73 74 72 69 6e 67 20 6f 72 20 63 6f 6e 74  y string or cont
3b80: 61 69 6e 73 20 6e 6f 74 68 69 6e 67 20 6f 74 68  ains nothing oth
3b90: 65 72 20 74 68 61 6e 20 77 68 69 74 65 73 70 61  er than whitespa
3ba0: 63 65 2c 20 63 6f 6d 6d 65 6e 74 73 2c 0a 2a 2a  ce, comments,.**
3bb0: 20 20 20 20 20 20 20 20 20 20 61 6e 64 2f 6f 72            and/or
3bc0: 20 73 65 6d 69 63 6f 6c 6f 6e 73 2c 20 74 68 65   semicolons, the
3bd0: 6e 20 72 65 73 75 6c 74 73 20 6f 66 20 5b 73 71  n results of [sq
3be0: 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
3bf0: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
3c00: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
3c10: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  , and [sqlite3_e
3c20: 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20  rrmsg16()].**   
3c30: 20 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 73         shall res
3c40: 65 74 20 74 6f 20 69 6e 64 69 63 61 74 65 20 6e  et to indicate n
3c50: 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20  o errors..**.** 
3c60: 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
3c70: 2a 2a 20 7b 41 31 32 31 34 31 7d 20 54 68 65 20  ** {A12141} The 
3c80: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
3c90: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
3ca0: 28 29 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 76  ()] must be an v
3cb0: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a  alid and open.**
3cc0: 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
3cd0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
3ce0: 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 32 7d 20  .**.** {A12142} 
3cf0: 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
3d00: 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
3d10: 20 62 65 20 63 6c 6f 73 65 64 20 77 68 69 6c 65   be closed while
3d20: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
3d30: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73  lite3_exec()] is
3d40: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   running..**.** 
3d50: 7b 41 31 32 31 34 33 7d 20 54 68 65 20 63 61 6c  {A12143} The cal
3d60: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68  ling function sh
3d70: 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c 69 74 65  ould use [sqlite
3d80: 33 5f 66 72 65 65 28 29 5d 20 74 6f 20 66 72 65  3_free()] to fre
3d90: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  e.**          th
3da0: 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a 65  e memory that *e
3db0: 72 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70 6f  rrmsg is left po
3dc0: 69 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20 74  inting at once t
3dd0: 68 65 20 65 72 72 6f 72 0a 2a 2a 20 20 20 20 20  he error.**     
3de0: 20 20 20 20 20 6d 65 73 73 61 67 65 20 69 73 20       message is 
3df0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3e00: 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 35 7d  ..**.** {A12145}
3e10: 20 54 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   The SQL stateme
3e20: 6e 74 20 74 65 78 74 20 69 6e 20 74 68 65 20 32  nt text in the 2
3e30: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
3e40: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3e50: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 75 73  .**          mus
3e60: 74 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  t remain unchang
3e70: 65 64 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ed while [sqlite
3e80: 33 5f 65 78 65 63 28 29 5d 20 69 73 20 72 75 6e  3_exec()] is run
3e90: 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
3ea0: 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c  ite3_exec(.  sql
3eb0: 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20  ite3*,          
3ec0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ed0: 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
3ee0: 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
3ef0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
3f00: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
3f10: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
3f20: 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
3f30: 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61  ed */.  int (*ca
3f40: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3f50: 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29  t,char**,char**)
3f60: 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66  ,  /* Callback f
3f70: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
3f80: 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  d *,            
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 2f 2a 20 31 73 74 20 61          /* 1st a
3fb0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62  rgument to callb
3fc0: 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ack */.  char **
3fd0: 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20  errmsg          
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ff0: 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
4000: 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
4010: 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
4020: 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65  REF: Result Code
4030: 73 20 7b 48 31 30 32 31 30 7d 20 3c 53 31 30 37  s {H10210} <S107
4040: 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
4050: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
4060: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
4070: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
4080: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
4090: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
40a0: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
40b0: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
40c0: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
40d0: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
40e0: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
40f0: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
4100: 20 69 6e 64 69 63 61 74 65 73 20 73 75 63 63 65   indicates succe
4110: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
4120: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63  *.** New error c
4130: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  odes may be adde
4140: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
4150: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
4160: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
4170: 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45  [SQLITE_IOERR_RE
4180: 41 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65  AD | extended re
4190: 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a 2f 0a 23  sult codes].*/.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
41b0: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
41c0: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73  * Successful res
41d0: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e  ult */./* beginn
41e0: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  ing-of-error-cod
41f0: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
4200: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20  LITE_ERROR      
4210: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72    1   /* SQL err
4220: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61  or or missing da
4230: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
4240: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41  e SQLITE_INTERNA
4250: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74  L     2   /* Int
4260: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f  ernal logic erro
4270: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23  r in SQLite */.#
4280: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45  define SQLITE_PE
4290: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f  RM         3   /
42a0: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73  * Access permiss
42b0: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
42c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
42d0: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a  RT        4   /*
42e0: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   Callback routin
42f0: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61  e requested an a
4300: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  bort */.#define 
4310: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20  SQLITE_BUSY     
4320: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64      5   /* The d
4330: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
4340: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
4350: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20  e SQLITE_LOCKED 
4360: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74        6   /* A t
4370: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61  able in the data
4380: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  base is locked *
4390: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
43a0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20  _NOMEM        7 
43b0: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20    /* A malloc() 
43c0: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e  failed */.#defin
43d0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
43e0: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74  Y     8   /* Att
43f0: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20  empt to write a 
4400: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73  readonly databas
4410: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4420: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20  ITE_INTERRUPT   
4430: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f   9   /* Operatio
4440: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20  n terminated by 
4450: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
4460: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t()*/.#define SQ
4470: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20  LITE_IOERR      
4480: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69   10   /* Some ki
4490: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65  nd of disk I/O e
44a0: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f  rror occurred */
44b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
44c0: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20  CORRUPT     11  
44d0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
44e0: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d   disk image is m
44f0: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66  alformed */.#def
4500: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ine SQLITE_NOTFO
4510: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 4e  UND    12   /* N
4520: 4f 54 20 55 53 45 44 2e 20 54 61 62 6c 65 20 6f  OT USED. Table o
4530: 72 20 72 65 63 6f 72 64 20 6e 6f 74 20 66 6f 75  r record not fou
4540: 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nd */.#define SQ
4550: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
4560: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
4570: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
4580: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
4590: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
45a0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
45b0: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
45c0: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
45d0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
45e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
45f0: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
4600: 4e 4f 54 20 55 53 45 44 2e 20 44 61 74 61 62 61  NOT USED. Databa
4610: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c  se lock protocol
4620: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
4630: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20  e SQLITE_EMPTY  
4640: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74       16   /* Dat
4650: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a  abase is empty *
4660: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4670: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20  _SCHEMA      17 
4680: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4690: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64  e schema changed
46a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
46b0: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31  TE_TOOBIG      1
46c0: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72  8   /* String or
46d0: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69   BLOB exceeds si
46e0: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66  ze limit */.#def
46f0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
4700: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41  RAINT  19   /* A
4710: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73  bort due to cons
4720: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
4730: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4740: 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32  TE_MISMATCH    2
4750: 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65  0   /* Data type
4760: 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65   mismatch */.#de
4770: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55  fine SQLITE_MISU
4780: 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20  SE      21   /* 
4790: 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63  Library used inc
47a0: 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66  orrectly */.#def
47b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53  ine SQLITE_NOLFS
47c0: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55         22   /* U
47d0: 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20  ses OS features 
47e0: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e  not supported on
47f0: 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   host */.#define
4800: 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20   SQLITE_AUTH    
4810: 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68      23   /* Auth
4820: 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64  orization denied
4830: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4840: 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32  TE_FORMAT      2
4850: 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79  4   /* Auxiliary
4860: 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74   database format
4870: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
4880: 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20  e SQLITE_RANGE  
4890: 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64       25   /* 2nd
48a0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
48b0: 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f  lite3_bind out o
48c0: 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69  f range */.#defi
48d0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42  ne SQLITE_NOTADB
48e0: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69        26   /* Fi
48f0: 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69  le opened that i
4900: 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
4910: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
4920: 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20   SQLITE_ROW     
4930: 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69      100  /* sqli
4940: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61  te3_step() has a
4950: 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79  nother row ready
4960: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4970: 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31  TE_DONE        1
4980: 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  01  /* sqlite3_s
4990: 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68  tep() has finish
49a0: 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a  ed executing */.
49b0: 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d  /* end-of-error-
49c0: 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  codes */../*.** 
49d0: 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64  CAPI3REF: Extend
49e0: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 20  ed Result Codes 
49f0: 7b 48 31 30 32 32 30 7d 20 3c 53 31 30 37 30 30  {H10220} <S10700
4a00: 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
4a10: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
4a20: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
4a30: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
4a40: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
4a50: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
4a60: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
4a70: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
4a80: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4a90: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4aa0: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4ab0: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
4ac0: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
4ad0: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
4ae0: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
4af0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
4b00: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
4b10: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
4b20: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
4b30: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
4b40: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
4b50: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
4b60: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
4b70: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
4b80: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
4b90: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
4ba0: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
4bb0: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
4bc0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
4bd0: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
4be0: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
4bf0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
4c00: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
4c10: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
4c20: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
4c30: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
4c40: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
4c50: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
4c60: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4c70: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4c80: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4c90: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4ca0: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4cb0: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4cc0: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
4cd0: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
4ce0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
4cf0: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
4d00: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4d10: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
4d20: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
4d30: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
4d40: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
4d50: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
4d60: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
4d70: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
4d80: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
4d90: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4da0: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
4db0: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
4dc0: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
4dd0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
4de0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
4df0: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
4e00: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
4e10: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
4e20: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
4e30: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
4e40: 6f 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  o..**.** INVARIA
4e50: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32  NTS:.**.** {H102
4e60: 32 33 7d 20 54 68 65 20 73 79 6d 62 6f 6c 69 63  23} The symbolic
4e70: 20 6e 61 6d 65 20 66 6f 72 20 61 6e 20 65 78 74   name for an ext
4e80: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4e90: 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 73  e shall contains
4ea0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72  .**          a r
4eb0: 65 6c 61 74 65 64 20 70 72 69 6d 61 72 79 20 72  elated primary r
4ec0: 65 73 75 6c 74 20 63 6f 64 65 20 61 73 20 61 20  esult code as a 
4ed0: 70 72 65 66 69 78 2e 0a 2a 2a 0a 2a 2a 20 7b 48  prefix..**.** {H
4ee0: 31 30 32 32 34 7d 20 50 72 69 6d 61 72 79 20 72  10224} Primary r
4ef0: 65 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73  esult code names
4f00: 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 61   shall contain a
4f10: 20 73 69 6e 67 6c 65 20 22 5f 22 20 63 68 61 72   single "_" char
4f20: 61 63 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  acter..**.** {H1
4f30: 30 32 32 35 7d 20 45 78 74 65 6e 64 65 64 20 72  0225} Extended r
4f40: 65 73 75 6c 74 20 63 6f 64 65 20 6e 61 6d 65 73  esult code names
4f50: 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69 6e 20 74   shall contain t
4f60: 77 6f 20 6f 72 20 6d 6f 72 65 20 22 5f 22 20 63  wo or more "_" c
4f70: 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
4f80: 20 7b 48 31 30 32 32 36 7d 20 54 68 65 20 6e 75   {H10226} The nu
4f90: 6d 65 72 69 63 20 76 61 6c 75 65 20 6f 66 20 61  meric value of a
4fa0: 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
4fb0: 74 20 63 6f 64 65 20 73 68 61 6c 6c 20 63 6f 6e  t code shall con
4fc0: 74 61 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  tain the.**     
4fd0: 20 20 20 20 20 6e 75 6d 65 72 69 63 20 76 61 6c       numeric val
4fe0: 75 65 20 6f 66 20 69 74 73 20 63 6f 72 72 65 73  ue of its corres
4ff0: 70 6f 6e 64 69 6e 67 20 70 72 69 6d 61 72 79 20  ponding primary 
5000: 72 65 73 75 6c 74 20 63 6f 64 65 20 69 6e 0a 2a  result code in.*
5010: 2a 20 20 20 20 20 20 20 20 20 20 69 74 73 20 6c  *          its l
5020: 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
5030: 20 38 20 62 69 74 73 2e 0a 2a 2f 0a 23 64 65 66   8 bits..*/.#def
5040: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5050: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
5060: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5070: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5080: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5090: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20  SHORT_READ      
50a0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
50b0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
50c0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
50d0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
50e0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
50f0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
5100: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
5110: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
5120: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5130: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5140: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
5150: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
5160: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5170: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
5180: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e  QLITE_IOERR_TRUN
5190: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53  CATE          (S
51a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
51b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
51d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
51e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c  LITE_IOERR | (7<
51f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5200: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b  ITE_IOERR_UNLOCK
5210: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5220: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
5230: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5240: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
5250: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5260: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38  TE_IOERR | (9<<8
5270: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5280: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20  E_IOERR_DELETE  
5290: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
52a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
52b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
52c0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
52d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
52e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38  E_IOERR | (11<<8
52f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5300: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20  E_IOERR_NOMEM   
5310: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5320: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38  E_IOERR | (12<<8
5330: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5340: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20  E_IOERR_ACCESS  
5350: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5360: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38  E_IOERR | (13<<8
5370: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5380: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53  E_IOERR_CHECKRES
5390: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54  ERVEDLOCK (SQLIT
53a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38  E_IOERR | (14<<8
53b0: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ))../*.** CAPI3R
53c0: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69  EF: Flags For Fi
53d0: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f  le Open Operatio
53e0: 6e 73 20 7b 48 31 30 32 33 30 7d 20 3c 48 31 31  ns {H10230} <H11
53f0: 31 32 30 3e 20 3c 48 31 32 37 30 30 3e 0a 2a 2a  120> <H12700>.**
5400: 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61  .** These bit va
5410: 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lues are intende
5420: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65  d for use in the
5430: 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65  .** 3rd paramete
5440: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
5450: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
5460: 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e  erface and.** in
5470: 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
5480: 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  er to the xOpen 
5490: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a  method of the.**
54a0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
54b0: 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e  bject..*/.#defin
54c0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  e SQLITE_OPEN_RE
54d0: 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30  ADONLY         0
54e0: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
54f0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  e SQLITE_OPEN_RE
5500: 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30  ADWRITE        0
5510: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
5520: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  e SQLITE_OPEN_CR
5530: 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30  EATE           0
5540: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
5550: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45  e SQLITE_OPEN_DE
5560: 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30  LETEONCLOSE    0
5570: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
5580: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
5590: 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30  CLUSIVE        0
55a0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
55b0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41  e SQLITE_OPEN_MA
55c0: 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30  IN_DB          0
55d0: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
55e0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45  e SQLITE_OPEN_TE
55f0: 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30  MP_DB          0
5600: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
5610: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52  e SQLITE_OPEN_TR
5620: 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30  ANSIENT_DB     0
5630: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
5640: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41  e SQLITE_OPEN_MA
5650: 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30  IN_JOURNAL     0
5660: 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e  x00000800.#defin
5670: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45  e SQLITE_OPEN_TE
5680: 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30  MP_JOURNAL     0
5690: 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e  x00001000.#defin
56a0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55  e SQLITE_OPEN_SU
56b0: 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30  BJOURNAL       0
56c0: 78 30 30 30 30 32 30 30 30 0a 23 64 65 66 69 6e  x00002000.#defin
56d0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41  e SQLITE_OPEN_MA
56e0: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30  STER_JOURNAL   0
56f0: 78 30 30 30 30 34 30 30 30 0a 23 64 65 66 69 6e  x00004000.#defin
5700: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f  e SQLITE_OPEN_NO
5710: 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30  MUTEX          0
5720: 78 30 30 30 30 38 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00008000../*.**
5730: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
5740: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
5750: 73 20 7b 48 31 30 32 34 30 7d 20 3c 48 31 31 31  s {H10240} <H111
5760: 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44  20>.**.** The xD
5770: 65 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65  eviceCapabilitie
5780: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
5790: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
57a0: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
57b0: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
57c0: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
57d0: 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65  tor of the these
57e0: 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65  .** bit values e
57f0: 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68  xpressing I/O ch
5800: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66  aracteristics of
5810: 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67   the mass storag
5820: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
5830: 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20   holds the file 
5840: 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
5850: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
5860: 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a   refers to..**.*
5870: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
5880: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
5890: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
58a0: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
58b0: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
58c0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
58d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
58e0: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
58f0: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
5900: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
5910: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
5920: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
5930: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
5940: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
5950: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
5960: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
5970: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
5980: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
5990: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
59a0: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
59b0: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
59c0: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
59d0: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
59e0: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
59f0: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
5a00: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
5a10: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
5a20: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
5a30: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
5a40: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
5a50: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
5a60: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
5a70: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
5a80: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
5a90: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
5aa0: 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66  Write()..*/.#def
5ab0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5ac0: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
5ad0: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
5ae0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5af0: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
5b00: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
5b10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5b20: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
5b30: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
5b40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5b50: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
5b60: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
5b70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5b80: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
5b90: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66   0x00000010.#def
5ba0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5bb0: 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20  _ATOMIC8K       
5bc0: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66   0x00000020.#def
5bd0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5be0: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20  _ATOMIC16K      
5bf0: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
5c00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5c10: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
5c20: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
5c30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5c40: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
5c50: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
5c60: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5c70: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
5c80: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
5c90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5ca0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
5cb0: 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a   0x00000400../*.
5cc0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
5cd0: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
5ce0: 20 7b 48 31 30 32 35 30 7d 20 3c 48 31 31 31 32   {H10250} <H1112
5cf0: 30 3e 20 3c 48 31 31 33 31 30 3e 0a 2a 2a 0a 2a  0> <H11310>.**.*
5d00: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
5d10: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
5d20: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
5d30: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
5d40: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
5d50: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
5d60: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
5d70: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
5d80: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
5d90: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
5da0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5db0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
5dc0: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
5dd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
5de0: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
5df0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5e00: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
5e10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5e20: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
5e30: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
5e40: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
5e50: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
5e60: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
5e70: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
5e80: 61 67 73 20 7b 48 31 30 32 36 30 7d 20 3c 48 31  ags {H10260} <H1
5e90: 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  1120>.**.** When
5ea0: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
5eb0: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
5ec0: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
5ed0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
5ee0: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
5ef0: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
5f00: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
5f10: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
5f20: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
5f30: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
5f40: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
5f50: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
5f60: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
5f70: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
5f80: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
5f90: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
5fa0: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
5fb0: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
5fc0: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
5fd0: 62 65 20 66 6c 75 73 68 65 64 2e 20 54 68 65 20  be flushed. The 
5fe0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
5ff0: 41 4c 20 66 6c 61 67 20 6d 65 61 6e 73 0a 2a 2a  AL flag means.**
6000: 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66   to use normal f
6010: 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73  sync() semantics
6020: 2e 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  . The SQLITE_SYN
6030: 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d 65 61 6e  C_FULL flag mean
6040: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20  s.** to use Mac 
6050: 4f 53 2d 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS-X style fulls
6060: 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66  ync instead of f
6070: 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64 65 66 69  sync()..*/.#defi
6080: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  ne SQLITE_SYNC_N
6090: 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30  ORMAL        0x0
60a0: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
60b0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20  ITE_SYNC_FULL   
60c0: 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23         0x00003.#
60d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
60e0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20  NC_DATAONLY     
60f0: 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20   0x00010../*.** 
6100: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
6110: 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65  erface Open File
6120: 20 48 61 6e 64 6c 65 20 7b 48 31 31 31 31 30 7d   Handle {H11110}
6130: 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S20110>.**.** 
6140: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
6150: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
6160: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
6170: 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a 20 69 6e   in the OS.** in
6180: 74 65 72 66 61 63 65 20 6c 61 79 65 72 2e 20 20  terface layer.  
6190: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
61a0: 74 65 72 66 61 63 65 20 69 6d 70 6c 65 6d 65 6e  terface implemen
61b0: 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20  tations will.** 
61c0: 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73  want to subclass
61d0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20   this object by 
61e0: 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69  appending additi
61f0: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66  onal fields.** f
6200: 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65  or their own use
6210: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20  .  The pMethods 
6220: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74  entry is a point
6230: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
6240: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6250: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
6260: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72  ines methods for
6270: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49   performing.** I
6280: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e  /O operations on
6290: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a   the open file..
62a0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
62b0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73  t sqlite3_file s
62c0: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72  qlite3_file;.str
62d0: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
62e0: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63   {.  const struc
62f0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
6300: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20  hods *pMethods; 
6310: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
6320: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a  an open file */.
6330: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
6340: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
6350: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65   File Virtual Me
6360: 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b 48 31  thods Object {H1
6370: 31 31 32 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a  1120} <S20110>.*
6380: 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20  *.** Every file 
6390: 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73  opened by the [s
63a0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70 65  qlite3_vfs] xOpe
63b0: 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74  n method populat
63c0: 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  es an.** [sqlite
63d0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28  3_file] object (
63e0: 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c  or, more commonl
63f0: 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66  y, a subclass of
6400: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
6410: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77  _file] object) w
6420: 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ith a pointer to
6430: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
6440: 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  this object..** 
6450: 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  This object defi
6460: 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20  nes the methods 
6470: 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20  used to perform 
6480: 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f  various operatio
6490: 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68  ns.** against th
64a0: 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72  e open file repr
64b0: 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b  esented by the [
64c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
64d0: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ject..**.** The 
64e0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
64f0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
6500: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
6510: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
6520: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
6530: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
6540: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
6550: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
6560: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
6570: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 2d 58  ce is a Mac OS-X
6580: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
6590: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
65a0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
65b0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
65c0: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
65d0: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
65e0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
65f0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
6600: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
6610: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
6620: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6630: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
6640: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
6650: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
6660: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6670: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
6680: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
6690: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
66a0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
66b0: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
66c0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
66d0: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
66e0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
66f0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
6700: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
6710: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
6720: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
6730: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
6740: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
6750: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
6760: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
6770: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
6780: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
6790: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
67a0: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
67b0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
67c0: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
67d0: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
67e0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
67f0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
6800: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
6810: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
6820: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
6830: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
6840: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
6850: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
6860: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
6870: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
6880: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
6890: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
68a0: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
68b0: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
68c0: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
68d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
68e0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
68f0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
6900: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
6910: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
6920: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
6930: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
6940: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
6950: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
6960: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
6970: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
6980: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
6990: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
69a0: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
69b0: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
69c0: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
69d0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
69e0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
69f0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
6a00: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
6a10: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
6a20: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
6a30: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
6a40: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
6a50: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
6a60: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
6a70: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
6a80: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
6a90: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
6aa0: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
6ab0: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
6ac0: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
6ad0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
6ae0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
6af0: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
6b00: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
6b10: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
6b20: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
6b30: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
6b40: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
6b50: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
6b60: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
6b70: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
6b80: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
6b90: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
6ba0: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 0a 2a 2a  id conflicts..**
6bb0: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
6bc0: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
6bd0: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
6be0: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
6bf0: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
6c00: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
6c10: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
6c20: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
6c30: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
6c40: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
6c50: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
6c60: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
6c70: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
6c80: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
6c90: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
6ca0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
6cb0: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
6cc0: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
6cd0: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
6ce0: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
6cf0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
6d00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6d10: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
6d20: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6d30: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
6d40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6d50: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
6d60: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6d70: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
6d80: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6d90: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
6da0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6db0: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
6dc0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6dd0: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
6de0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6df0: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
6e00: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
6e10: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
6e20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
6e30: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
6e40: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6e50: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
6e60: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
6e70: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6e80: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
6e90: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
6ea0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
6eb0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
6ec0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6ed0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
6ee0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
6ef0: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
6f00: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
6f10: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
6f20: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
6f30: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
6f40: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
6f50: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
6f60: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
6f70: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6f80: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
6f90: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
6fa0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
6fb0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
6fc0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
6fd0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
6fe0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
6ff0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
7000: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
7010: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
7020: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
7030: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
7040: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
7050: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
7060: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
7070: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
7080: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
7090: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
70a0: 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ()..*/.typedef s
70b0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
70c0: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
70d0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  _io_methods;.str
70e0: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
70f0: 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69  ethods {.  int i
7100: 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
7110: 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  *xClose)(sqlite3
7120: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
7130: 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f  *xRead)(sqlite3_
7140: 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e  file*, void*, in
7150: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
7160: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
7170: 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71  int (*xWrite)(sq
7180: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e  lite3_file*, con
7190: 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  st void*, int iA
71a0: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
71b0: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
71c0: 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c  (*xTruncate)(sql
71d0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
71e0: 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b  te3_int64 size);
71f0: 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28  .  int (*xSync)(
7200: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7210: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74  nt flags);.  int
7220: 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71   (*xFileSize)(sq
7230: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
7240: 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a  ite3_int64 *pSiz
7250: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63  e);.  int (*xLoc
7260: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
7270: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
7280: 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33  xUnlock)(sqlite3
7290: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
72a0: 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65  int (*xCheckRese
72b0: 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65  rvedLock)(sqlite
72c0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52  3_file*, int *pR
72d0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
72e0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71  xFileControl)(sq
72f0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7300: 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29   op, void *pArg)
7310: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f  ;.  int (*xSecto
7320: 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  rSize)(sqlite3_f
7330: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
7340: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
7350: 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66  stics)(sqlite3_f
7360: 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69  ile*);.  /* Addi
7370: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d  tional methods m
7380: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
7390: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a  uture releases *
73a0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
73b0: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46  3REF: Standard F
73c0: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f  ile Control Opco
73d0: 64 65 73 20 7b 48 31 31 33 31 30 7d 20 3c 53 33  des {H11310} <S3
73e0: 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0800>.**.** Thes
73f0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
7400: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
7410: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
7420: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
7430: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
7440: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
7450: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
7460: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
7470: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
7480: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ace..**.** The [
7490: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
74a0: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69  KSTATE] opcode i
74b0: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
74c0: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
74d0: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
74e0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
74f0: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68  thod to write th
7500: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20  e current state 
7510: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28  of.** the lock (
7520: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c  one of [SQLITE_L
7530: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49  OCK_NONE], [SQLI
7540: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
7550: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  .** [SQLITE_LOCK
7560: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c  _RESERVED], [SQL
7570: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
7580: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f  ], or [SQLITE_LO
7590: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a  CK_EXCLUSIVE]).*
75a0: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  * into an intege
75b0: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20  r that the pArg 
75c0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
75d0: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c  to. This capabil
75e0: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64  ity.** is used d
75f0: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e  uring testing an
7600: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
7610: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
7620: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a  n SQLITE_TEST.**
7630: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a   is defined..*/.
7640: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
7650: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
7660: 20 20 20 20 20 20 31 0a 0a 2f 2a 0a 2a 2a 20 43        1../*.** C
7670: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48  API3REF: Mutex H
7680: 61 6e 64 6c 65 20 7b 48 31 37 31 31 30 7d 20 3c  andle {H17110} <
7690: 53 32 30 31 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20130>.**.** Th
76a0: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
76b0: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
76c0: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
76d0: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
76e0: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
76f0: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
7700: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
7710: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
7720: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
7730: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
7740: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
7750: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
7760: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
7770: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
7780: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
7790: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
77a0: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
77b0: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
77c0: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
77d0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
77e0: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
77f0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
7800: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7810: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
7820: 6a 65 63 74 20 7b 48 31 31 31 34 30 7d 20 3c 53  ject {H11140} <S
7830: 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 6e 20  20100>.**.** An 
7840: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
7850: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
7860: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
7870: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
7880: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
7890: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
78a0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
78b0: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
78c0: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
78d0: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
78e0: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
78f0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
7900: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  "..**.** The val
7910: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
7920: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
7930: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
7940: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
7950: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
7960: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
7970: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
7980: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
7990: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
79a0: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
79b0: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
79c0: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
79d0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
79e0: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
79f0: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
7a00: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
7a10: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
7a20: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
7a30: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
7a40: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
7a50: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
7a60: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
7a70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
7a80: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
7a90: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
7aa0: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
7ab0: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
7ac0: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
7ad0: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
7ae0: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
7af0: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
7b00: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
7b10: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
7b20: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
7b30: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
7b40: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
7b50: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
7b60: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
7b70: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
7b80: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
7b90: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
7ba0: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
7bb0: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
7bc0: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
7bd0: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
7be0: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
7bf0: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
7c00: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
7c10: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
7c20: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
7c30: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
7c40: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
7c50: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
7c60: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
7c70: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
7c80: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
7c90: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
7ca0: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
7cb0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
7cc0: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
7cd0: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
7ce0: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
7cf0: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
7d00: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
7d10: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
7d20: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
7d30: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
7d40: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
7d50: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
7d60: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
7d70: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
7d80: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
7d90: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
7da0: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
7db0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
7dc0: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
7dd0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
7de0: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
7df0: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
7e00: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
7e10: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
7e20: 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 31 7d 20 53  **.** {H11141} S
7e30: 51 4c 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61  QLite will guara
7e40: 6e 74 65 65 20 74 68 61 74 20 74 68 65 20 7a 46  ntee that the zF
7e50: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
7e60: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
7e70: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
7e80: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
7e90: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
7ea0: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
7eb0: 29 2e 20 20 53 51 4c 69 74 65 20 66 75 72 74 68  ).  SQLite furth
7ec0: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  er guarantees th
7ed0: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  at.** the string
7ee0: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
7ef0: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
7f00: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
7f10: 2a 20 63 61 6c 6c 65 64 2e 20 7b 45 4e 44 7d 20  * called. {END} 
7f20: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
7f30: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 73  previous sentens
7f40: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
7f50: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
7f60: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
7f70: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
7f80: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
7f90: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
7fa0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
7fb0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
7fc0: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
7fd0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 78 4f   parameter is xO
7fe0: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
7ff0: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
8000: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 69 74 65 20  .** must invite 
8010: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
8020: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
8030: 69 6c 65 2e 20 20 57 68 65 6e 65 76 65 72 20 74  ile.  Whenever t
8040: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
8050: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
8060: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
8070: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
8080: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
8090: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
80a0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
80b0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
80c0: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 32 7d  ..**.** {H11142}
80d0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
80e0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
80f0: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
8100: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
8110: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
8120: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
8130: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
8140: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
8150: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
8160: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
8170: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
8180: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
8190: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
81a0: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
81b0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
81c0: 7b 45 4e 44 7d 0a 2a 2a 20 49 66 20 78 4f 70 65  {END}.** If xOpe
81d0: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
81e0: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
81f0: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
8200: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
8210: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
8220: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
8230: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
8240: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
8250: 2a 0a 2a 2a 20 7b 48 31 31 31 34 33 7d 20 53 51  *.** {H11143} SQ
8260: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61  Lite will also a
8270: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
8280: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
8290: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20   the xOpen().** 
82a0: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20  call, depending 
82b0: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65  on the object be
82c0: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a  ing opened:.**.*
82d0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
82e0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
82f0: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
8300: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
8310: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
8320: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
8330: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
8340: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
8350: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
8360: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
8370: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
8380: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
8390: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
83a0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
83b0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
83c0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  JOURNAL].** </ul
83d0: 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68  > {END}.**.** Th
83e0: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
83f0: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
8400: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
8410: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
8420: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
8430: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
8440: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
8450: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
8460: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
8470: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
8480: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
8490: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
84a0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
84b0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
84c0: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
84d0: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
84e0: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
84f0: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
8500: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
8510: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
8520: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
8530: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
8540: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
8550: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
8560: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
8570: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
8580: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
8590: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
85a0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
85b0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
85c0: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
85d0: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
85e0: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
85f0: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
8600: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
8610: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
8620: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
8630: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
8640: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
8650: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
8660: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
8670: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
8680: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
8690: 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 35 7d 20 54  **.** {H11145} T
86a0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
86b0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
86c0: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
86d0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
86e0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
86f0: 69 73 20 63 6c 6f 73 65 64 2e 20 20 7b 48 31 31  is closed.  {H11
8700: 31 34 36 7d 20 54 68 65 20 5b 53 51 4c 49 54 45  146} The [SQLITE
8710: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
8720: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  OSE].** will be 
8730: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61  set for TEMP  da
8740: 74 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c  tabases, journal
8750: 73 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75  s and for subjou
8760: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  rnals..**.** {H1
8770: 31 31 34 37 7d 20 54 68 65 20 5b 53 51 4c 49 54  1147} The [SQLIT
8780: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
8790: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
87a0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
87b0: 6f 70 65 6e 65 64 0a 2a 2a 20 66 6f 72 20 65 78  opened.** for ex
87c0: 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 20  clusive access. 
87d0: 20 54 68 69 73 20 66 6c 61 67 20 69 73 20 73 65   This flag is se
87e0: 74 20 66 6f 72 20 61 6c 6c 20 66 69 6c 65 73 20  t for all files 
87f0: 65 78 63 65 70 74 0a 2a 2a 20 66 6f 72 20 74 68  except.** for th
8800: 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
8810: 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  file..**.** {H11
8820: 31 34 38 7d 20 41 74 20 6c 65 61 73 74 20 73 7a  148} At least sz
8830: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
8840: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63  memory are alloc
8850: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  ated by SQLite.*
8860: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
8870: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
8880: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
8890: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
88a0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
88b0: 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 78 4f 70  . {END}  The xOp
88c0: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
88d0: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
88e0: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
88f0: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
8900: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
8910: 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 39 7d 20  .**.** {H11149} 
8920: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
8930: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
8940: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
8950: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
8960: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
8970: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
8980: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
8990: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
89a0: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
89b0: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
89c0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
89d0: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
89e0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
89f0: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
8a00: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
8a10: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 7b  east readable. {
8a20: 45 4e 44 7d 20 20 54 68 65 20 66 69 6c 65 20 63  END}  The file c
8a30: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
8a40: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  tory..**.** {H11
8a50: 31 35 30 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c  150} SQLite will
8a60: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65   always allocate
8a70: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68   at least mxPath
8a80: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72  name+1 bytes for
8a90: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62   the.** output b
8aa0: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e  uffer xFullPathn
8ab0: 61 6d 65 2e 20 7b 48 31 31 31 35 31 7d 20 54 68  ame. {H11151} Th
8ac0: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
8ad0: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
8ae0: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
8af0: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
8b00: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
8b10: 6f 64 73 2e 20 7b 45 4e 44 7d 20 20 49 66 20 74  ods. {END}  If t
8b20: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
8b30: 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65  .** is not large
8b40: 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45   enough, [SQLITE
8b50: 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c  _CANTOPEN] shoul
8b60: 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53  d be returned. S
8b70: 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20  ince this is.** 
8b80: 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74  handled as a fat
8b90: 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69  al error by SQLi
8ba0: 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e  te, vfs implemen
8bb0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65  tations should e
8bc0: 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72  ndeavor.** to pr
8bd0: 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65  event this by se
8be0: 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65  tting mxPathname
8bf0: 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74   to a sufficient
8c00: 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a  ly large value..
8c10: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  **.** The xRando
8c20: 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28  mness(), xSleep(
8c30: 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54  ), and xCurrentT
8c40: 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  ime() interfaces
8c50: 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74 72 69  .** are not stri
8c60: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
8c70: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
8c80: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
8c90: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
8ca0: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
8cb0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
8cc0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
8cd0: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
8ce0: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
8cf0: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
8d00: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
8d10: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
8d20: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
8d30: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
8d40: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
8d50: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
8d60: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
8d70: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
8d80: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
8d90: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
8da0: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
8db0: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
8dc0: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
8dd0: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 54 68  conds given.  Th
8de0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
8df0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
8e00: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
8e10: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
8e20: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
8e30: 74 69 6d 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  time..*/.typedef
8e40: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
8e50: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
8e60: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
8e70: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
8e80: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
8e90: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
8ea0: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a  rsion number */.
8eb0: 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20    int szOsFile; 
8ec0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69             /* Si
8ed0: 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64  ze of subclassed
8ee0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f   sqlite3_file */
8ef0: 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d  .  int mxPathnam
8f00: 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  e;          /* M
8f10: 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68  aximum file path
8f20: 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20  name length */. 
8f30: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e   sqlite3_vfs *pN
8f40: 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78  ext;      /* Nex
8f50: 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53  t registered VFS
8f60: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
8f70: 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f   *zName;       /
8f80: 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76  * Name of this v
8f90: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
8fa0: 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  em */.  void *pA
8fb0: 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
8fc0: 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61   /* Pointer to a
8fd0: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69  pplication-speci
8fe0: 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e  fic data */.  in
8ff0: 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
9000: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
9010: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
9020: 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20  te3_file*,.     
9030: 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c            int fl
9040: 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c  ags, int *pOutFl
9050: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  ags);.  int (*xD
9060: 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76  elete)(sqlite3_v
9070: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
9080: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63  *zName, int sync
9090: 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41  Dir);.  int (*xA
90a0: 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  ccess)(sqlite3_v
90b0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
90c0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67  *zName, int flag
90d0: 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  s, int *pResOut)
90e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50  ;.  int (*xFullP
90f0: 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  athname)(sqlite3
9100: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
9110: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f  r *zName, int nO
9120: 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  ut, char *zOut);
9130: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70  .  void *(*xDlOp
9140: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
9150: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
9160: 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64  ilename);.  void
9170: 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c   (*xDlError)(sql
9180: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
9190: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72  Byte, char *zErr
91a0: 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Msg);.  void *(*
91b0: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
91c0: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
91d0: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
91e0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c  ;.  void (*xDlCl
91f0: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ose)(sqlite3_vfs
9200: 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  *, void*);.  int
9210: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
9220: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
9230: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
9240: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Out);.  int (*xS
9250: 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66  leep)(sqlite3_vf
9260: 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63  s*, int microsec
9270: 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  onds);.  int (*x
9280: 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c  CurrentTime)(sql
9290: 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c  ite3_vfs*, doubl
92a0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  e*);.  int (*xGe
92b0: 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69  tLastError)(sqli
92c0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63  te3_vfs*, int, c
92d0: 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77  har *);.  /* New
92e0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
92f0: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
9300: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
9310: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
9320: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
9330: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
9340: 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b  s happens. */.};
9350: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
9360: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
9370: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
9380: 6f 64 20 7b 48 31 31 31 39 30 7d 20 3c 48 31 31  od {H11190} <H11
9390: 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31  140>.**.** {H111
93a0: 39 31 7d 20 54 68 65 73 65 20 69 6e 74 65 67 65  91} These intege
93b0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
93c0: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
93d0: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
93e0: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
93f0: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
9400: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
9410: 63 74 2e 20 7b 45 4e 44 7d 20 20 54 68 65 79 20  ct. {END}  They 
9420: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
9430: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
9440: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
9450: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
9460: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 7b 48 31 31  ing for..** {H11
9470: 31 39 32 7d 20 57 69 74 68 20 53 51 4c 49 54 45  192} With SQLITE
9480: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
9490: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
94a0: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
94b0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
94c0: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
94d0: 7b 48 31 31 31 39 33 7d 20 57 69 74 68 20 53 51  {H11193} With SQ
94e0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
94f0: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
9500: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
9510: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
9520: 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61  file is both rea
9530: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
9540: 6c 65 2e 0a 2a 2a 20 7b 48 31 31 31 39 34 7d 20  le..** {H11194} 
9550: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
9560: 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63  SS_READ, the xAc
9570: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
9580: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
9590: 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  e file is readab
95a0: 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  le..*/.#define S
95b0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
95c0: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
95d0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
95e0: 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 66 69  EADWRITE 1.#defi
95f0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
9600: 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a  _READ      2../*
9610: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
9620: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
9630: 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48 31 30  ite Library {H10
9640: 31 33 30 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33  130} <S20000><S3
9650: 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0100>.**.** The 
9660: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9670: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
9680: 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
9690: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
96a0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
96b0: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
96c0: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
96d0: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
96e0: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
96f0: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
9700: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  ialize()..**.** 
9710: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
9720: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
9730: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
9740: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
9750: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
9760: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9770: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
9780: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
9790: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
97a0: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
97b0: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
97c0: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
97d0: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
97e0: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
97f0: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
9800: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 4f  3_shutdown().  O
9810: 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65  nly an effective
9820: 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69   call.** of sqli
9830: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9840: 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61   does any initia
9850: 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f  lization.  All o
9860: 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72  ther calls.** ar
9870: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
9880: 73 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  s..**.** Among o
9890: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 73 71 6c  ther things, sql
98a0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
98b0: 29 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  ) shall invoke.*
98c0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
98d0: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
98e0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
98f0: 6e 28 29 0a 2a 2a 20 73 68 61 6c 6c 20 69 6e 76  n().** shall inv
9900: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
9910: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nd()..**.** The 
9920: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9930: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
9940: 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20 6f  urns SQLITE_OK o
9950: 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49 66  n success..** If
9960: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
9970: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
9980: 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65  lize() is unable
9990: 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a   to initialize.*
99a0: 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70  * the library (p
99b0: 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61  erhaps it is una
99c0: 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
99d0: 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63  a needed resourc
99e0: 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d  e such.** as a m
99f0: 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73  utex) it returns
9a00: 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
9a10: 20 6f 74 68 65 72 20 74 68 61 6e 20 53 51 4c 49   other than SQLI
9a20: 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  TE_OK..**.** The
9a30: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9a40: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
9a50: 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
9a60: 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
9a70: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
9a80: 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
9a90: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
9aa0: 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
9ab0: 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
9ac0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9ad0: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
9ae0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
9af0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
9b00: 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
9b10: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
9b20: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
9b30: 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
9b40: 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
9b50: 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
9b60: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
9b70: 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
9b80: 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
9b90: 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
9ba0: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c   However, if SQL
9bb0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
9bc0: 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
9bd0: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 0a 2a 2a  OMIT_AUTOINIT.**
9be0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
9bf0: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
9c00: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
9c10: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
9c20: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
9c30: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
9c40: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
9c50: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
9c60: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
9c70: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
9c80: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
9c90: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
9ca0: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
9cb0: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
9cc0: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
9cd0: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
9ce0: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
9cf0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9d00: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
9d10: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
9d20: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
9d30: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
9d40: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
9d50: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
9d60: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
9d70: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
9d80: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
9d90: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
9da0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
9db0: 74 68 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  th SQLITE_OMIT_A
9dc0: 55 54 4f 49 4e 49 54 20 6d 69 67 68 74 20 62 65  UTOINIT might be
9dd0: 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61  come the.** defa
9de0: 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20  ult behavior in 
9df0: 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
9e00: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
9e10: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
9e20: 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69  _os_init() routi
9e30: 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e  ne does operatin
9e40: 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
9e50: 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74  c.** initializat
9e60: 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ion of the SQLit
9e70: 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  e library.  The 
9e80: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
9e90: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f  .** routine undo
9ea0: 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
9eb0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
9ec0: 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73  ().  Typical tas
9ed0: 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ks.** performed 
9ee0: 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  by these routine
9ef0: 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61  s include alloca
9f00: 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tion or dealloca
9f10: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69  tion.** of stati
9f20: 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69  c resources, ini
9f30: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67  tialization of g
9f40: 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c  lobal variables,
9f50: 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61  .** setting up a
9f60: 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
9f70: 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f  3_vfs] module, o
9f80: 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20  r setting up.** 
9f90: 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  a default config
9fa0: 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73  uration using [s
9fb0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
9fc0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
9fd0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
9fe0: 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68  ever invoke eith
9ff0: 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  er sqlite3_os_in
a000: 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  it().** or sqlit
a010: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65  e3_os_end() dire
a020: 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69  ctly.  The appli
a030: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e  cation should on
a040: 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ly invoke.** sql
a050: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
a060: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68  ) and sqlite3_sh
a070: 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73  utdown().  The s
a080: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a090: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
a0a0: 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69   called automati
a0b0: 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
a0c0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
a0d0: 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  d.** sqlite3_os_
a0e0: 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20  end() is called 
a0f0: 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  by sqlite3_shutd
a100: 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69  own().  Appropri
a110: 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ate.** implement
a120: 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74  ations for sqlit
a130: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
a140: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
a150: 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69  ).** are built i
a160: 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20  nto SQLite when 
a170: 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66  it is compiled f
a180: 6f 72 20 75 6e 69 78 2c 20 77 69 6e 64 6f 77 73  or unix, windows
a190: 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a 2a 20 57 68  , or os/2..** Wh
a1a0: 65 6e 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68  en built for oth
a1b0: 65 72 20 70 6c 61 74 66 6f 72 6d 73 20 28 75 73  er platforms (us
a1c0: 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  ing the SQLITE_O
a1d0: 53 5f 4f 54 48 45 52 3d 31 20 63 6f 6d 70 69 6c  S_OTHER=1 compil
a1e0: 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
a1f0: 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
a200: 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
a210: 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
a220: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
a230: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a240: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
a250: 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
a260: 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
a270: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
a280: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
a290: 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
a2a0: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
a2b0: 73 74 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  st return SQLITE
a2c0: 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 20 61  _OK on success a
a2d0: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
a2e0: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
a2f0: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
a300: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
a310: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
a320: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
a330: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
a340: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
a350: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
a360: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
a370: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
a380: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
a390: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 20 7b 48  QLite Library {H
a3a0: 31 30 31 34 35 7d 20 3c 53 32 30 30 30 30 3e 3c  10145} <S20000><
a3b0: 53 33 30 32 30 30 3e 0a 2a 2a 20 45 58 50 45 52  S30200>.** EXPER
a3c0: 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68  IMENTAL.**.** Th
a3d0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
a3e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
a3f0: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
a400: 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
a410: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
a420: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
a430: 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
a440: 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
a450: 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
a460: 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
a470: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
a480: 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
a490: 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
a4a0: 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
a4b0: 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
a4c0: 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
a4d0: 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
a4e0: 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
a4f0: 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
a500: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
a510: 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
a520: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
a530: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
a540: 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
a550: 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70  eadsafe.  The ap
a560: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
a570: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t insure that no
a580: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
a590: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
a5a0: 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
a5b0: 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
a5c0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
a5d0: 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72  is running.  Fur
a5e0: 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65  thermore, sqlite
a5f0: 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61  3_config().** ma
a600: 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
a610: 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
a620: 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
a630: 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
a640: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a650: 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
a660: 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
a670: 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
a680: 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
a690: 68 61 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  hat sqlite3_conf
a6a0: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
a6b0: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
a6c0: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
a6d0: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
a6e0: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
a6f0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a700: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
a710: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
a720: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
a730: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
a740: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
a750: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63  SINGLETHREAD | c
a760: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
a770: 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
a780: 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
a790: 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
a7a0: 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
a7b0: 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
a7c0: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
a7d0: 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
a7e0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
a7f0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
a800: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
a810: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
a820: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
a830: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 61 20 63  ..**.** When a c
a840: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
a850: 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
a860: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
a870: 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a  urns SQLITE_OK..
a880: 2a 2a 20 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  ** If the option
a890: 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
a8a0: 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
a8b0: 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
a8c0: 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
a8d0: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
a8e0: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
a8f0: 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73   code]..*/.int s
a900: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
a910: 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
a920: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
a930: 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
a940: 6e 65 63 74 69 6f 6e 73 20 20 7b 48 31 30 31 38  nections  {H1018
a950: 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45  0} <S20000>.** E
a960: 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
a970: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
a980: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
a990: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
a9a0: 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ake configuratio
a9b0: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
a9c0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
a9d0: 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e  ection].  The in
a9e0: 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c  terface is simil
a9f0: 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ar to.** [sqlite
aa00: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65  3_config()] exce
aa10: 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e  pt that the chan
aa20: 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73  ges apply to a s
aa30: 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61  ingle.** [databa
aa40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
aa50: 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
aa60: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29   first argument)
aa70: 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
aa80: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e  3_db_config() in
aa90: 74 65 72 66 61 63 65 20 63 61 6e 20 6f 6e 6c 79  terface can only
aaa0: 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61   be used immedia
aab0: 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68  tely after.** th
aac0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
aad0: 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64  ction is created
aae0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
aaf0: 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  open()],.** [sql
ab00: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
ab10: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
ab20: 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20  _v2()].  .**.** 
ab30: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
ab40: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  ent to sqlite3_d
ab50: 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e  b_config(D,V,...
ab60: 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e  )  is the.** con
ab70: 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20  figuration verb 
ab80: 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  - an integer cod
ab90: 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  e that indicates
aba0: 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20   what.** aspect 
abb0: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
abc0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
abd0: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
abe0: 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68  ..** The only ch
abf0: 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76 61  oice for this va
ac00: 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  lue is [SQLITE_D
ac10: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
ac20: 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73  E]..** New verbs
ac30: 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62   are likely to b
ac40: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
ac50: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
ac60: 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  Lite..** Additio
ac70: 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65  nal arguments de
ac80: 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62  pend on the verb
ac90: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
aca0: 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74  _db_config(sqlit
acb0: 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e  e3*, int op, ...
acc0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
acd0: 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
ace0: 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b  ation Routines {
acf0: 48 31 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e  H10155} <S20120>
ad00: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
ad10: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
ad20: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
ad30: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
ad40: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
ad50: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
ad60: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
ad70: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
ad80: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
ad90: 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
ada0: 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
adb0: 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
adc0: 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
add0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
ade0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
adf0: 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
ae00: 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
ae10: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65  e3_config()] whe
ae20: 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
ae30: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ion option is.**
ae40: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
ae50: 4d 41 4c 4c 4f 43 5d 2e 20 20 42 79 20 63 72 65  MALLOC].  By cre
ae60: 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
ae70: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
ae80: 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
ae90: 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
aea0: 6f 6e 66 69 67 28 29 5d 20 64 75 72 69 6e 67 20  onfig()] during 
aeb0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
aec0: 6e 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  n.** application
aed0: 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
aee0: 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
aef0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
af00: 62 73 79 73 74 65 6d 0a 2a 2a 20 66 6f 72 20 53  bsystem.** for S
af10: 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
af20: 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
af30: 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
af40: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
af50: 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
af60: 69 74 68 20 61 20 62 75 69 6c 74 2d 69 6e 20 6d  ith a built-in m
af70: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
af80: 74 68 61 74 20 69 73 0a 2a 2a 20 70 65 72 66 65  that is.** perfe
af90: 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f  ctly adequate fo
afa0: 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69  r the overwhelmi
afb0: 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61  ng majority of a
afc0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61  pplications.** a
afd0: 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a  nd that this obj
afe0: 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66  ect is only usef
aff0: 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e  ul to a tiny min
b000: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
b010: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70  tions.** with sp
b020: 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79  ecialized memory
b030: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
b040: 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20  irements.  This 
b050: 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73  object is.** als
b060: 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  o used during te
b070: 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20  sting of SQLite 
b080: 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63  in order to spec
b090: 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
b0a0: 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
b0b0: 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75  ocator that simu
b0c0: 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74  lates memory out
b0d0: 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69  -of-memory condi
b0e0: 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65  tions in.** orde
b0f0: 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74  r to verify that
b100: 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73   SQLite recovers
b110: 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d   gracefully from
b120: 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69   such.** conditi
b130: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ons..**.** The x
b140: 4d 61 6c 6c 6f 63 2c 20 78 46 72 65 65 2c 20 61  Malloc, xFree, a
b150: 6e 64 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68  nd xRealloc meth
b160: 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69  ods must work li
b170: 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63  ke the.** malloc
b180: 28 29 2c 20 66 72 65 65 28 29 2c 20 61 6e 64 20  (), free(), and 
b190: 72 65 61 6c 6c 6f 63 28 29 20 66 75 6e 63 74 69  realloc() functi
b1a0: 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
b1b0: 6e 64 61 72 64 20 6c 69 62 72 61 72 79 2e 0a 2a  ndard library..*
b1c0: 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c  *.** xSize shoul
b1d0: 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c  d return the all
b1e0: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61  ocated size of a
b1f0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
b200: 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  on.** previously
b210: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78   obtained from x
b220: 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c  Malloc or xReall
b230: 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74  oc.  The allocat
b240: 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c  ed size.** is al
b250: 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73  ways at least as
b260: 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75   big as the requ
b270: 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d  ested size but m
b280: 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a  ay be larger..**
b290: 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70  .** The xRoundup
b2a0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
b2b0: 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68  what would be th
b2c0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
b2d0: 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20   of.** a memory 
b2e0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e  allocation given
b2f0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
b300: 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d  quested size.  M
b310: 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ost memory.** al
b320: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
b330: 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  p memory allocat
b340: 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f  ions at least to
b350: 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70   the next multip
b360: 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d  le.** of 8.  Som
b370: 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  e allocators rou
b380: 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65  nd up to a large
b390: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f  r multiple or to
b3a0: 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a   a power of 2..*
b3b0: 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
b3c0: 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
b3d0: 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
b3e0: 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78  ocator.  (For ex
b3f0: 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
b400: 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
b410: 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
b420: 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
b430: 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
b440: 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
b450: 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
b460: 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
b470: 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
b480: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
b490: 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
b4a0: 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
b4b0: 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
b4c0: 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
b4d0: 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
b4e0: 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
b4f0: 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
b500: 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
b510: 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2f 0a  d xShutdown..*/.
b520: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
b530: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
b540: 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
b550: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
b560: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
b570: 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
b580: 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
b590: 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
b5a0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
b5b0: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
b5c0: 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
b5d0: 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
b5e0: 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
b5f0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
b600: 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
b610: 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
b620: 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
b630: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
b640: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
b650: 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
b660: 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
b670: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
b680: 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
b690: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
b6a0: 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
b6b0: 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
b6c0: 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
b6d0: 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
b6e0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
b6f0: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
b700: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
b710: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
b720: 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
b730: 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
b740: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
b750: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
b760: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
b770: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
b780: 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
b790: 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
b7a0: 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
b7b0: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
b7c0: 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b  ration Options {
b7d0: 48 31 30 31 36 30 7d 20 3c 53 32 30 30 30 30 3e  H10160} <S20000>
b7e0: 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
b7f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
b800: 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
b810: 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
b820: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
b830: 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
b840: 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
b850: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
b860: 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
b870: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
b880: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
b890: 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
b8a0: 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
b8b0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
b8c0: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
b8d0: 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
b8e0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
b8f0: 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
b900: 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
b910: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
b920: 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
b930: 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
b940: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
b950: 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
b960: 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
b970: 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71  worked.  The [sq
b980: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
b990: 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
b9a0: 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
b9b0: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
b9c0: 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
b9d0: 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
b9e0: 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
b9f0: 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
ba00: 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
ba10: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
ba20: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
ba30: 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
ba40: 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
ba50: 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
ba60: 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69  tion.  This opti
ba70: 6f 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  on disables.** a
ba80: 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
ba90: 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
baa0: 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
bab0: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
bac0: 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
bad0: 20 74 68 72 65 61 64 2e 3c 2f 64 64 3e 0a 2a 2a   thread.</dd>.**
bae0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
baf0: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
bb00: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
bb10: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
bb20: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
bb30: 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f  ion.  This optio
bb40: 6e 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  n disables.** mu
bb50: 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
bb60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
bb70: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
bb80: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
bb90: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
bba0: 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
bbb0: 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
bbc0: 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
bbd0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
bbe0: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
bbf0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
bc00: 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
bc10: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
bc20: 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
bc30: 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
bc40: 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
bc50: 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
bc60: 6e 76 69 72 6f 6e 6d 65 6e 74 2e 3c 2f 64 64 3e  nvironment.</dd>
bc70: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
bc80: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
bc90: 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
bca0: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
bcb0: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
bcc0: 70 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f 70 74  ption.  This opt
bcd0: 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
bce0: 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
bcf0: 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
bd00: 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
bd10: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
bd20: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
bd30: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
bd40: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
bd50: 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
bd60: 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
bd70: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
bd80: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
bd90: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
bda0: 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
bdb0: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
bdc0: 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
bdd0: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
bde0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bdf0: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
be00: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
be10: 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
be20: 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
be30: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
be40: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
be50: 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
be60: 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
be70: 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
be80: 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
be90: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
bea0: 0a 2a 2a 0a 2a 2a 20 3c 70 3e 54 68 69 73 20 63  .**.** <p>This c
beb0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
bec0: 69 6f 6e 20 6d 65 72 65 6c 79 20 73 65 74 73 20  ion merely sets 
bed0: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
bee0: 78 20 0a 2a 2a 20 62 65 68 61 76 69 6f 72 20 74  x .** behavior t
bef0: 6f 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  o serialize acce
bf00: 73 73 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20  ss to [database 
bf10: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e 20 20 49  connections].  I
bf20: 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 5b 64 61  ndividual.** [da
bf30: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
bf40: 6e 73 5d 20 63 61 6e 20 6f 76 65 72 72 69 64 65  ns] can override
bf50: 20 74 68 69 73 20 73 65 74 74 69 6e 67 0a 2a 2a   this setting.**
bf60: 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
bf70: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
bf80: 20 66 6c 61 67 20 74 6f 20 5b 73 71 6c 69 74 65   flag to [sqlite
bf90: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 3c 2f 70  3_open_v2()].</p
bfa0: 3e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  ></dd>.**.** <dt
bfb0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
bfc0: 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
bfd0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
bfe0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
bff0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
c000: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
c010: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
c020: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
c030: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
c040: 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
c050: 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
c060: 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
c070: 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
c080: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
c090: 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
c0a0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
c0b0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
c0c0: 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
c0d0: 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a  to SQLite.</dd>.
c0e0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
c0f0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
c100: 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  C</dt>.** <dd>Th
c110: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
c120: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
c130: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
c140: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
c150: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
c160: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
c170: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
c180: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
c190: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
c1a0: 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
c1b0: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
c1c0: 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
c1d0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
c1e0: 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20  utines..** This 
c1f0: 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
c200: 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
c210: 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
c220: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
c230: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
c240: 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
c250: 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
c260: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
c270: 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
c280: 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
c290: 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a  r example.</dd>.
c2a0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
c2b0: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
c2c0: 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  S</dt>.** <dd>Th
c2d0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
c2e0: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
c2f0: 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74  of type int, int
c300: 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a  erpreted as a .*
c310: 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68  * boolean, which
c320: 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
c330: 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74  bles the collect
c340: 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c  ion of memory al
c350: 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61  location .** sta
c360: 74 69 73 74 69 63 73 2e 20 57 68 65 6e 20 64 69  tistics. When di
c370: 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c  sabled, the foll
c380: 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
c390: 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 0a  erfaces become .
c3a0: 2a 2a 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  ** non-operation
c3b0: 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
c3c0: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
c3d0: 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
c3e0: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
c3f0: 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
c400: 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
c410: 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
c420: 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  eap_limit()].** 
c430: 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
c440: 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c  status()].**   <
c450: 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  /ul>.** </dd>.**
c460: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
c470: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
c480: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
c490: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
c4a0: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
c4b0: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
c4c0: 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
c4d0: 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
c4e0: 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
c4f0: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41  ee arguments:  A
c500: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
c510: 6d 65 6d 6f 72 79 2c 20 74 68 65 0a 2a 2a 20 73  memory, the.** s
c520: 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61  ize of each scra
c530: 74 63 68 20 62 75 66 66 65 72 20 28 73 7a 29 2c  tch buffer (sz),
c540: 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
c550: 6f 66 20 62 75 66 66 65 72 73 20 28 4e 29 2e 20  of buffers (N). 
c560: 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
c570: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75  ent must be a mu
c580: 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68  ltiple of 16. Th
c590: 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 73  e sz parameter s
c5a0: 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77 20 62  hould be a few b
c5b0: 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74  ytes.** larger t
c5c0: 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c 20 73  han the actual s
c5d0: 63 72 61 74 63 68 20 73 70 61 63 65 20 72 65 71  cratch space req
c5e0: 75 69 72 65 64 20 64 75 65 20 69 6e 74 65 72 6e  uired due intern
c5f0: 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20  al overhead..** 
c600: 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67  The first.** arg
c610: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69  ument should poi
c620: 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74  nt to an allocat
c630: 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ion of at least 
c640: 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65  sz*N bytes of me
c650: 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  mory..** SQLite 
c660: 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65  will use no more
c670: 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63   than one scratc
c680: 68 20 62 75 66 66 65 72 20 61 74 20 6f 6e 63 65  h buffer at once
c690: 20 70 65 72 20 74 68 72 65 61 64 2c 20 73 6f 0a   per thread, so.
c6a0: 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73  ** N should be s
c6b0: 65 74 20 74 6f 20 74 68 65 20 65 78 70 65 63 74  et to the expect
c6c0: 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  ed maximum numbe
c6d0: 72 20 6f 66 20 74 68 72 65 61 64 73 2e 20 20 54  r of threads.  T
c6e0: 68 65 20 73 7a 0a 2a 2a 20 70 61 72 61 6d 65 74  he sz.** paramet
c6f0: 65 72 20 73 68 6f 75 6c 64 20 62 65 20 36 20 74  er should be 6 t
c700: 69 6d 65 73 20 74 68 65 20 73 69 7a 65 20 6f 66  imes the size of
c710: 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
c720: 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e  abase page size.
c730: 0a 2a 2a 20 53 63 72 61 74 63 68 20 62 75 66 66  .** Scratch buff
c740: 65 72 73 20 61 72 65 20 75 73 65 64 20 61 73 20  ers are used as 
c750: 70 61 72 74 20 6f 66 20 74 68 65 20 62 74 72 65  part of the btre
c760: 65 20 62 61 6c 61 6e 63 65 20 6f 70 65 72 61 74  e balance operat
c770: 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54 68 65 20  ion.  If.** The 
c780: 62 74 72 65 65 20 62 61 6c 61 6e 63 65 72 20 6e  btree balancer n
c790: 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 20  eeds additional 
c7a0: 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68  memory beyond wh
c7b0: 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
c7c0: 79 0a 2a 2a 20 73 63 72 61 74 63 68 20 62 75 66  y.** scratch buf
c7d0: 66 65 72 73 20 6f 72 20 69 66 20 6e 6f 20 73 63  fers or if no sc
c7e0: 72 61 74 63 68 20 62 75 66 66 65 72 20 73 70 61  ratch buffer spa
c7f0: 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 2c  ce is specified,
c800: 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20   then SQLite.** 
c810: 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  goes to [sqlite3
c820: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f 20 6f 62  _malloc()] to ob
c830: 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  tain the memory 
c840: 69 74 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a  it needs.</dd>.*
c850: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
c860: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
c870: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69  </dt>.** <dd>Thi
c880: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
c890: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
c8a0: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
c8b0: 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
c8c0: 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  r.** the databas
c8d0: 65 20 70 61 67 65 20 63 61 63 68 65 2e 20 20 54  e page cache.  T
c8e0: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
c8f0: 72 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e  rguments: A poin
c900: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 6d 65  ter to the.** me
c910: 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f  mory, the size o
c920: 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66  f each page buff
c930: 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65  er (sz), and the
c940: 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73   number of pages
c950: 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
c960: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
c970: 20 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20   a power of two 
c980: 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
c990: 33 32 37 36 38 2e 20 20 54 68 65 20 66 69 72 73  32768.  The firs
c9a0: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
c9b0: 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e  ould point to an
c9c0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61   allocation of a
c9d0: 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
c9e0: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
c9f0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
ca00: 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76   the memory prov
ca10: 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ided by the firs
ca20: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61  t argument to sa
ca30: 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d  tisfy its.** mem
ca40: 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68  ory needs for th
ca50: 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20  e first N pages 
ca60: 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20  that it adds to 
ca70: 63 61 63 68 65 2e 20 20 49 66 20 61 64 64 69 74  cache.  If addit
ca80: 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
ca90: 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
caa0: 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
cab0: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
cac0: 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  this option, the
cad0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73  n.** SQLite goes
cae0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
caf0: 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
cb00: 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67  dditional storag
cb10: 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20  e space..** The 
cb20: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
cb30: 69 67 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 20  ight use one or 
cb40: 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e 20 62 75  more of the N bu
cb50: 66 66 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a  ffers to hold .*
cb60: 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74  * memory account
cb70: 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  ing information.
cb80: 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
cb90: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  >SQLITE_CONFIG_H
cba0: 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAP</dt>.** <dd>
cbb0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
cbc0: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
cbd0: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
cbe0: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  t SQLite will us
cbf0: 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20  e.** for all of 
cc00: 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
cc10: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
cc20: 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65  eds beyond those
cc30: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72   provided.** for
cc40: 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
cc50: 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20  IG_SCRATCH] and 
cc60: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
cc70: 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68  AGECACHE]..** Th
cc80: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
cc90: 67 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74  guments: A point
cca0: 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
ccb0: 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  , the number of.
ccc0: 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
ccd0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
cce0: 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
ccf0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 20  llocation size. 
cd00: 20 49 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   If.** the first
cd10: 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
cd20: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
cd30: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
cd40: 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
cd50: 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
cd60: 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
cd70: 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
cd80: 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
cd90: 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
cda0: 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
cdb0: 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
cdc0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
cdd0: 4f 43 5d 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20  OC].  If the.** 
cde0: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
cdf0: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65  s not NULL and e
ce00: 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
ce10: 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
ce20: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
ce30: 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20  LE_MEMSYS5] are 
ce40: 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68  defined, then th
ce50: 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
ce60: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
ce70: 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
ce80: 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
ce90: 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
cea0: 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 3c 2f  ocation needs.</
ceb0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
cec0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
ced0: 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  X</dt>.** <dd>Th
cee0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
cef0: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
cf00: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
cf10: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
cf20: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
cf30: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
cf40: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
cf50: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
cf60: 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
cf70: 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
cf80: 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
cf90: 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
cfa0: 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lace.** the mute
cfb0: 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
cfc0: 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64   into SQLite.</d
cfd0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
cfe0: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
cff0: 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
d000: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
d010: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
d020: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
d030: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
d040: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
d050: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
d060: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
d070: 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
d080: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
d090: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
d0a0: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
d0b0: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
d0c0: 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
d0d0: 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  nes..** This opt
d0e0: 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
d0f0: 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
d100: 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
d110: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
d120: 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
d130: 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
d140: 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
d150: 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
d160: 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
d170: 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
d180: 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  le.</dd>.**.** <
d190: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
d1a0: 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
d1b0: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
d1c0: 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
d1d0: 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
d1e0: 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c  rmine the defaul
d1f0: 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 63  t.** memory allc
d200: 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73 69 64 65 20  ation lookaside 
d210: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 20 54  optimization.  T
d220: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
d230: 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
d240: 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
d250: 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
d260: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
d270: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
d280: 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
d290: 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
d2a0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 3c 2f  se connection.</
d2b0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
d2c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d2d0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
d2e0: 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
d2f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d300: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
d310: 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
d320: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
d330: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
d340: 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
d350: 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
d360: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
d370: 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
d380: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
d390: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
d3a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
d3b0: 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
d3c0: 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
d3d0: 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
d3e0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d3f0: 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
d400: 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
d410: 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
d420: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
d430: 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
d440: 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
d450: 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
d460: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
d470: 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
d480: 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
d490: 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
d4a0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
d4b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
d4c0: 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
d4d0: 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
d4e0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
d4f0: 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
d500: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
d510: 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
d520: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
d530: 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
d540: 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
d550: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
d560: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d570: 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
d580: 4f 43 20 20 20 31 32 20 20 2f 2a 20 69 6e 74 20  OC   12  /* int 
d590: 74 68 72 65 73 68 6f 6c 64 20 2a 2f 0a 23 64 65  threshold */.#de
d5a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
d5b0: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
d5c0: 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
d5d0: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
d5e0: 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
d5f0: 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 37 30   Options {H10170
d600: 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58  } <S20000>.** EX
d610: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
d620: 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
d630: 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
d640: 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
d650: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
d660: 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
d670: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
d680: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
d690: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
d6a0: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
d6b0: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
d6c0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d6d0: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
d6e0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
d6f0: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
d700: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
d710: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
d720: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
d730: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
d740: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
d750: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
d760: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
d770: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
d780: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
d790: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
d7a0: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
d7b0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
d7c0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
d7d0: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
d7e0: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
d7f0: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
d800: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
d810: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
d820: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
d830: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
d840: 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
d850: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
d860: 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
d870: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
d880: 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
d890: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
d8a0: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
d8b0: 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
d8c0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
d8d0: 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
d8e0: 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
d8f0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
d900: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
d910: 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
d920: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
d930: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
d940: 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
d950: 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
d960: 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
d970: 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
d980: 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ry.  The first.*
d990: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62  * argument may b
d9a0: 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
d9b0: 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
d9c0: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 6c 6f   allocate the lo
d9d0: 6f 6b 61 73 69 64 65 0a 2a 2a 20 62 75 66 66 65  okaside.** buffe
d9e0: 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
d9f0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
da00: 5d 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ].  The second a
da10: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
da20: 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
da30: 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
da40: 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 74 68 69  slot and the thi
da50: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
da60: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
da70: 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
da80: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
da90: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
daa0: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
dab0: 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
dac0: 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
dad0: 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
dae0: 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
daf0: 75 6d 65 6e 74 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  uments.</dd>.**.
db00: 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
db10: 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
db20: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
db30: 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
db40: 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a  int int */.../*.
db50: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
db60: 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
db70: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
db80: 6f 64 65 73 20 7b 48 31 32 32 30 30 7d 20 3c 53  odes {H12200} <S
db90: 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  10700>.**.** The
dba0: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
dbb0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
dbc0: 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
dbd0: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
dbe0: 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
dbf0: 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
dc00: 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 54  ure of SQLite. T
dc10: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
dc20: 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
dc30: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
dc40: 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
dc50: 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
dc60: 20 63 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e   considerations.
dc70: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
dc80: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 31  S:.**.** {H12201
dc90: 7d 20 45 61 63 68 20 6e 65 77 20 5b 64 61 74 61  } Each new [data
dca0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
dcb0: 20 73 68 61 6c 6c 20 68 61 76 65 20 74 68 65 0a   shall have the.
dcc0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74  **          [ext
dcd0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
dce0: 65 73 5d 20 66 65 61 74 75 72 65 20 64 69 73 61  es] feature disa
dcf0: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
dd00: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 32 7d 20  .**.** {H12202} 
dd10: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  The [sqlite3_ext
dd20: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
dd30: 65 73 28 44 2c 46 29 5d 20 69 6e 74 65 72 66 61  es(D,F)] interfa
dd40: 63 65 20 73 68 61 6c 6c 20 65 6e 61 62 6c 65 0a  ce shall enable.
dd50: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74  **          [ext
dd60: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
dd70: 65 73 5d 20 66 6f 72 20 74 68 65 20 20 5b 64 61  es] for the  [da
dd80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
dd90: 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20  n] D.**         
dda0: 20 69 66 20 74 68 65 20 46 20 70 61 72 61 6d 65   if the F parame
ddb0: 74 65 72 20 69 73 20 74 72 75 65 2c 20 6f 72 20  ter is true, or 
ddc0: 64 69 73 61 62 6c 65 20 74 68 65 6d 20 69 66 20  disable them if 
ddd0: 46 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69  F is false..*/.i
dde0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
ddf0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
de00: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
de10: 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
de20: 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
de30: 65 72 74 20 52 6f 77 69 64 20 7b 48 31 32 32 32  ert Rowid {H1222
de40: 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
de50: 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20  * Each entry in 
de60: 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
de70: 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
de80: 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
de90: 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
dea0: 20 74 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68   the "rowid". Th
deb0: 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
dec0: 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
ded0: 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
dee0: 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
def0: 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
df00: 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
df10: 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
df20: 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
df30: 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
df40: 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
df50: 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
df60: 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
df70: 74 79 70 65 20 49 4e 54 45 47 45 52 20 50 52 49  type INTEGER PRI
df80: 4d 41 52 59 20 4b 45 59 20 74 68 65 6e 20 74 68  MARY KEY then th
df90: 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
dfa0: 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
dfb0: 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
dfc0: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
dfd0: 72 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69  returns the rowi
dfe0: 64 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65  d of the most re
dff0: 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66  cent.** successf
e000: 75 6c 20 49 4e 53 45 52 54 20 69 6e 74 6f 20 74  ul INSERT into t
e010: 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d  he database from
e020: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
e030: 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  onnection].** in
e040: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
e050: 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75 63 63  ent.  If no succ
e060: 65 73 73 66 75 6c 20 49 4e 53 45 52 54 73 0a 2a  essful INSERTs.*
e070: 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  * have ever occu
e080: 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74  rred on that dat
e090: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e0a0: 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  , zero is return
e0b0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
e0c0: 49 4e 53 45 52 54 20 6f 63 63 75 72 73 20 77 69  INSERT occurs wi
e0d0: 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
e0e0: 74 68 65 6e 20 74 68 65 20 72 6f 77 69 64 20 6f  then the rowid o
e0f0: 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a  f the inserted.*
e100: 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65  * row is returne
e110: 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  d by this routin
e120: 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  e as long as the
e130: 20 74 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e   trigger is runn
e140: 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65  ing..** But once
e150: 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72   the trigger ter
e160: 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c  minates, the val
e170: 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
e180: 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
e190: 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61  everts to the la
e1a0: 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65  st value inserte
e1b0: 64 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  d before the tri
e1c0: 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a 0a 2a  gger fired..**.*
e1d0: 2a 20 41 6e 20 49 4e 53 45 52 54 20 74 68 61 74  * An INSERT that
e1e0: 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20   fails due to a 
e1f0: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
e200: 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a  tion is not a.**
e210: 20 73 75 63 63 65 73 73 66 75 6c 20 49 4e 53 45   successful INSE
e220: 52 54 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  RT and does not 
e230: 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
e240: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
e250: 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54  s.** routine.  T
e260: 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41  hus INSERT OR FA
e270: 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47  IL, INSERT OR IG
e280: 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20  NORE, INSERT OR 
e290: 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64  ROLLBACK,.** and
e2a0: 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54   INSERT OR ABORT
e2b0: 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73   make no changes
e2c0: 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76   to the return v
e2d0: 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  alue of this.** 
e2e0: 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65  routine when the
e2f0: 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69  ir insertion fai
e300: 6c 73 2e 20 20 57 68 65 6e 20 49 4e 53 45 52 54  ls.  When INSERT
e310: 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
e320: 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
e330: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
e340: 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
e350: 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
e360: 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
e370: 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
e380: 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
e390: 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
e3a0: 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
e3b0: 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
e3c0: 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
e3d0: 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
e3e0: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
e3f0: 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
e400: 63 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68  ce..**.** For th
e410: 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
e420: 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 49  is routine, an I
e430: 4e 53 45 52 54 20 69 73 20 63 6f 6e 73 69 64 65  NSERT is conside
e440: 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
e450: 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
e460: 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
e470: 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
e480: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
e490: 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32 31 7d  :.**.** {H12221}
e4a0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61   The [sqlite3_la
e4b0: 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
e4c0: 29 5d 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  )] function retu
e4d0: 72 6e 73 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a  rns the rowid.**
e4e0: 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
e4f0: 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63   most recent suc
e500: 63 65 73 73 66 75 6c 20 49 4e 53 45 52 54 20 70  cessful INSERT p
e510: 65 72 66 6f 72 6d 65 64 20 6f 6e 20 74 68 65 20  erformed on the 
e520: 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
e530: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e540: 63 74 69 6f 6e 5d 20 61 6e 64 20 77 69 74 68 69  ction] and withi
e550: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69  n the same or hi
e560: 67 68 65 72 20 6c 65 76 65 6c 0a 2a 2a 20 20 20  gher level.**   
e570: 20 20 20 20 20 20 20 74 72 69 67 67 65 72 20 63         trigger c
e580: 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20  ontext, or zero 
e590: 69 66 20 74 68 65 72 65 20 68 61 76 65 20 62 65  if there have be
e5a0: 65 6e 20 6e 6f 20 71 75 61 6c 69 66 79 69 6e 67  en no qualifying
e5b0: 20 69 6e 73 65 72 74 73 2e 0a 2a 2a 0a 2a 2a 20   inserts..**.** 
e5c0: 7b 48 31 32 32 32 33 7d 20 54 68 65 20 5b 73 71  {H12223} The [sq
e5d0: 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
e5e0: 74 5f 72 6f 77 69 64 28 29 5d 20 66 75 6e 63 74  t_rowid()] funct
e5f0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
e600: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 61 6d 65  **          same
e610: 20 76 61 6c 75 65 20 77 68 65 6e 20 63 61 6c 6c   value when call
e620: 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
e630: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
e640: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d 6d  .**          imm
e650: 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20  ediately before 
e660: 61 6e 64 20 61 66 74 65 72 20 61 20 52 4f 4c 4c  and after a ROLL
e670: 42 41 43 4b 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55  BACK..**.** ASSU
e680: 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  MPTIONS:.**.** {
e690: 41 31 32 32 33 32 7d 20 49 66 20 61 20 73 65 70  A12232} If a sep
e6a0: 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
e6b0: 66 6f 72 6d 73 20 61 20 6e 65 77 20 49 4e 53 45  forms a new INSE
e6c0: 52 54 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  RT on the same.*
e6d0: 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
e6e0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
e6f0: 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
e700: 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
e710: 77 69 64 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  wid()].**       
e720: 20 20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72     function is r
e730: 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
e740: 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
e750: 20 69 6e 73 65 72 74 20 72 6f 77 69 64 2c 0a 2a   insert rowid,.*
e760: 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20  *          then 
e770: 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
e780: 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
e790: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
e7a0: 28 29 5d 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ()] is.**       
e7b0: 20 20 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65     unpredictable
e7c0: 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
e7d0: 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
e7e0: 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
e7f0: 2a 20 20 20 20 20 20 20 20 20 20 6c 61 73 74 20  *          last 
e800: 69 6e 73 65 72 74 20 72 6f 77 69 64 2e 0a 2a 2f  insert rowid..*/
e810: 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
e820: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
e830: 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
e840: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
e850: 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
e860: 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
e870: 64 69 66 69 65 64 20 7b 48 31 32 32 34 30 7d 20  dified {H12240} 
e880: 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S10600>.**.** T
e890: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
e8a0: 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
e8b0: 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73  of database rows
e8c0: 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67   that were chang
e8d0: 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65  ed.** or inserte
e8e0: 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20  d or deleted by 
e8f0: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
e900: 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20  y completed SQL 
e910: 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20  statement.** on 
e920: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
e930: 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
e940: 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
e950: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 4f   parameter..** O
e960: 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74  nly changes that
e970: 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70   are directly sp
e980: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 49  ecified by the I
e990: 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 0a 2a  NSERT, UPDATE,.*
e9a0: 2a 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  * or DELETE stat
e9b0: 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
e9c0: 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
e9d0: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
e9e0: 2a 2a 20 74 72 69 67 67 65 72 73 20 61 72 65 20  ** triggers are 
e9f0: 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65  not counted. Use
ea00: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
ea10: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
ea20: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69  unction.** to fi
ea30: 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
ea40: 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69  ber of changes i
ea50: 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
ea60: 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
ea70: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f  ers..**.** A "ro
ea80: 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
ea90: 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
eaa0: 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
eab0: 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
eac0: 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
ead0: 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
eae0: 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
eaf0: 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
eb00: 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
eb10: 66 66 65 63 74 73 20 6f 66 20 52 45 50 4c 41 43  ffects of REPLAC
eb20: 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  E constraint res
eb30: 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c  olution,.** roll
eb40: 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63  back, ABORT proc
eb50: 65 73 73 69 6e 67 2c 20 44 52 4f 50 20 54 41 42  essing, DROP TAB
eb60: 4c 45 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74  LE, or by any ot
eb70: 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d  her.** mechanism
eb80: 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
eb90: 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  s direct row cha
eba0: 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74  nges..**.** A "t
ebb0: 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20  rigger context" 
ebc0: 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78  is a scope of ex
ebd0: 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67  ecution that beg
ebe0: 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20  ins and.** ends 
ebf0: 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20  with the script 
ec00: 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 4d  of a trigger.  M
ec10: 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ost SQL statemen
ec20: 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61  ts are.** evalua
ec30: 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61  ted outside of a
ec40: 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69  ny trigger.  Thi
ec50: 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65  s is the "top le
ec60: 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20  vel".** trigger 
ec70: 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74  context.  If a t
ec80: 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f  rigger fires fro
ec90: 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
eca0: 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65   a.** new trigge
ecb0: 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74  r context is ent
ecc0: 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72  ered for the dur
ecd0: 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e  ation of that on
ece0: 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53  e.** trigger.  S
ecf0: 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74  ubtriggers creat
ed00: 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f  e subcontexts fo
ed10: 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e  r their duration
ed20: 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20  ..**.** Calling 
ed30: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
ed40: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   or [sqlite3_ste
ed50: 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79  p()] recursively
ed60: 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65   does.** not cre
ed70: 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65  ate a new trigge
ed80: 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
ed90: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
eda0: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
edb0: 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20  r of direct row 
edc0: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a  changes in the.*
edd0: 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  * most recent IN
ede0: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
edf0: 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
ee00: 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  t within the sam
ee10: 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  e.** trigger con
ee20: 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73  text..**.** Thus
ee30: 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72  , when called fr
ee40: 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
ee50: 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
ee60: 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e  returns the.** n
ee70: 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
ee80: 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
ee90: 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
eea0: 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
eeb0: 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72   that also occur
eec0: 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c  red at the top l
eed0: 65 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 74 68  evel.  Within th
eee0: 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67  e body of a trig
eef0: 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69  ger,.** the sqli
ef00: 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  te3_changes() in
ef10: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63  terface can be c
ef20: 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68  alled to find th
ef30: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
ef40: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
ef50: 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
ef60: 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
ef70: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
ef80: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ** statement wit
ef90: 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
efa0: 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
efb0: 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
efc0: 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65  e number returne
efd0: 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
efe0: 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61  de changes.** ca
eff0: 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67  used by subtrigg
f000: 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20  ers since those 
f010: 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63  have their own c
f020: 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51  ontext..**.** SQ
f030: 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
f040: 74 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c  the command "DEL
f050: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20  ETE FROM table" 
f060: 77 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20  without a WHERE 
f070: 63 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f  clause.** by dro
f080: 70 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61  pping and recrea
f090: 74 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20  ting the table. 
f0a0: 20 28 54 68 69 73 20 69 73 20 6d 75 63 68 20 66   (This is much f
f0b0: 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69 6e 67  aster than going
f0c0: 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e 64 20  .** through and 
f0d0: 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76 69 64  deleting individ
f0e0: 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f  ual elements fro
f0f0: 6d 20 74 68 65 20 74 61 62 6c 65 2e 29 20 20 42  m the table.)  B
f100: 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a 2a  ecause of this.*
f110: 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20  * optimization, 
f120: 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69 6e  the deletions in
f130: 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61   "DELETE FROM ta
f140: 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f 77  ble" are not row
f150: 20 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a 20   changes and.** 
f160: 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75 6e  will not be coun
f170: 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
f180: 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72 20  e3_changes() or 
f190: 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
f1a0: 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75 6e  hanges()].** fun
f1b0: 63 74 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c 65  ctions, regardle
f1c0: 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ss of the number
f1d0: 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68 61   of elements tha
f1e0: 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c 6c  t were originall
f1f0: 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61 62 6c  y.** in the tabl
f200: 65 2e 20 20 54 6f 20 67 65 74 20 61 6e 20 61 63  e.  To get an ac
f210: 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66 20  curate count of 
f220: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
f230: 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65 0a  ws deleted, use.
f240: 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  ** "DELETE FROM 
f250: 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20 69  table WHERE 1" i
f260: 6e 73 74 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e  nstead..**.** IN
f270: 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
f280: 7b 48 31 32 32 34 31 7d 20 54 68 65 20 5b 73 71  {H12241} The [sq
f290: 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
f2a0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
f2b0: 72 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  return the numbe
f2c0: 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  r of.**         
f2d0: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
f2e0: 73 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  sed by the most 
f2f0: 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
f300: 50 44 41 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20  PDATE,.**       
f310: 20 20 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61     or DELETE sta
f320: 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 73 61  tement on the sa
f330: 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
f340: 65 63 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20  ection and.**   
f350: 20 20 20 20 20 20 20 77 69 74 68 69 6e 20 74 68         within th
f360: 65 20 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72  e same or higher
f370: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
f380: 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65  , or zero if the
f390: 72 65 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20  re have.**      
f3a0: 20 20 20 20 6e 6f 74 20 62 65 65 6e 20 61 6e 79      not been any
f3b0: 20 71 75 61 6c 69 66 79 69 6e 67 20 72 6f 77 20   qualifying row 
f3c0: 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b  changes..**.** {
f3d0: 48 31 32 32 34 33 7d 20 53 74 61 74 65 6d 65 6e  H12243} Statemen
f3e0: 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  ts of the form "
f3f0: 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
f400: 65 6e 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a  ename" with no.*
f410: 2a 20 20 20 20 20 20 20 20 20 20 57 48 45 52 45  *          WHERE
f420: 20 63 6c 61 75 73 65 20 73 68 61 6c 6c 20 63 61   clause shall ca
f430: 75 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 63  use subsequent c
f440: 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20  alls to.**      
f450: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 68 61      [sqlite3_cha
f460: 6e 67 65 73 28 29 5d 20 74 6f 20 72 65 74 75 72  nges()] to retur
f470: 6e 20 7a 65 72 6f 2c 20 72 65 67 61 72 64 6c 65  n zero, regardle
f480: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ss of the.**    
f490: 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20        number of 
f4a0: 72 6f 77 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20  rows originally 
f4b0: 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 0a 2a 2a  in the table..**
f4c0: 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
f4d0: 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 35 32 7d 20  .**.** {A12252} 
f4e0: 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
f4f0: 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
f500: 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
f510: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f520: 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  on.**          w
f530: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
f540: 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
f550: 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
f560: 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20  ue returned.**  
f570: 20 20 20 20 20 20 20 20 69 73 20 75 6e 70 72 65          is unpre
f580: 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
f590: 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
f5a0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
f5b0: 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
f5c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f5d0: 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
f5e0: 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48  Rows Modified {H
f5f0: 31 32 32 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a  12260} <S10600>.
f600: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
f610: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
f620: 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68  number of row ch
f630: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
f640: 49 4e 53 45 52 54 2c 0a 2a 2a 20 55 50 44 41 54  INSERT,.** UPDAT
f650: 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
f660: 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65  ements since the
f670: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
f680: 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65  ction] was opene
f690: 64 2e 0a 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20  d..** The count 
f6a0: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61  includes all cha
f6b0: 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72  nges from all tr
f6c0: 69 67 67 65 72 20 63 6f 6e 74 65 78 74 73 2e 20  igger contexts. 
f6d0: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65   However,.** the
f6e0: 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
f6f0: 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20  include changes 
f700: 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
f710: 74 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72  t REPLACE constr
f720: 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c  aints,.** do rol
f730: 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20  lbacks or ABORT 
f740: 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 44  processing, or D
f750: 52 4f 50 20 74 61 62 6c 65 20 70 72 6f 63 65 73  ROP table proces
f760: 73 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61  sing..** The cha
f770: 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  nges are counted
f780: 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
f790: 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d  statement that m
f7a0: 61 6b 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20  akes them is.** 
f7b0: 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
f7c0: 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
f7d0: 6e 64 6c 65 20 69 73 20 70 61 73 73 65 64 20 74  ndle is passed t
f7e0: 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
f7f0: 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
f800: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
f810: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d  .**.** SQLite im
f820: 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d  plements the com
f830: 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f  mand "DELETE FRO
f840: 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74  M table" without
f850: 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a   a WHERE clause.
f860: 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61  ** by dropping a
f870: 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74 68  nd recreating th
f880: 65 20 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20  e table.  (This 
f890: 69 73 20 6d 75 63 68 20 66 61 73 74 65 72 20 74  is much faster t
f8a0: 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72  han going.** thr
f8b0: 6f 75 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e  ough and deletin
f8c0: 67 20 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65  g individual ele
f8d0: 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74  ments from the t
f8e0: 61 62 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20  able.)  Because 
f8f0: 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d  of this.** optim
f900: 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c  ization, the del
f910: 65 74 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54  etions in "DELET
f920: 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72  E FROM table" ar
f930: 65 20 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65  e not row change
f940: 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f  s and.** will no
f950: 74 20 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20  t be counted by 
f960: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
f970: 67 65 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65  ges() or [sqlite
f980: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
f990: 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c  )].** functions,
f9a0: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
f9b0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65  he number of ele
f9c0: 6d 65 6e 74 73 20 74 68 61 74 20 77 65 72 65 20  ments that were 
f9d0: 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e  originally.** in
f9e0: 20 74 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20   the table.  To 
f9f0: 67 65 74 20 61 6e 20 61 63 63 75 72 61 74 65 20  get an accurate 
fa00: 63 6f 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d  count of the num
fa10: 62 65 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65  ber of rows dele
fa20: 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c  ted, use.** "DEL
fa30: 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57  ETE FROM table W
fa40: 48 45 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e  HERE 1" instead.
fa50: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
fa60: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
fa70: 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
fa80: 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  e..**.** INVARIA
fa90: 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  NTS:.**.** {H122
faa0: 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  61} The [sqlite3
fab0: 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
fac0: 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f  ] returns the to
fad0: 74 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20 20  tal number.**   
fae0: 20 20 20 20 20 20 20 6f 66 20 72 6f 77 20 63 68         of row ch
faf0: 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
fb00: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
fb10: 61 6e 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  and/or DELETE.**
fb20: 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d            statem
fb30: 65 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  ents on the same
fb40: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
fb50: 63 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a 2a  ction], in any.*
fb60: 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 67 67  *          trigg
fb70: 65 72 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e 63  er context, sinc
fb80: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
fb90: 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 63 72  onnection was cr
fba0: 65 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  eated..**.** {H1
fbb0: 32 32 36 33 7d 20 53 74 61 74 65 6d 65 6e 74 73  2263} Statements
fbc0: 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45   of the form "DE
fbd0: 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e  LETE FROM tablen
fbe0: 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20  ame" with no.** 
fbf0: 20 20 20 20 20 20 20 20 20 57 48 45 52 45 20 63           WHERE c
fc00: 6c 61 75 73 65 20 73 68 61 6c 6c 20 6e 6f 74 20  lause shall not 
fc10: 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
fc20: 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20   returned.**    
fc30: 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65        by [sqlite
fc40: 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
fc50: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50  )]..**.** ASSUMP
fc60: 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
fc70: 32 32 36 34 7d 20 49 66 20 61 20 73 65 70 61 72  2264} If a separ
fc80: 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
fc90: 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
fca0: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
fcb0: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  nnection.**     
fcc0: 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c 69       while [sqli
fcd0: 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
fce0: 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
fcf0: 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
fd00: 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
fd10: 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
fd20: 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
fd30: 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
fd40: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
fd50: 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
fd60: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
fd70: 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
fd80: 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
fd90: 20 7b 48 31 32 32 37 30 7d 20 3c 53 33 30 35 30   {H12270} <S3050
fda0: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0>.**.** This fu
fdb0: 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e  nction causes an
fdc0: 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61  y pending databa
fdd0: 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  se operation to 
fde0: 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74  abort and.** ret
fdf0: 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69  urn at its earli
fe00: 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e  est opportunity.
fe10: 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
fe20: 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61   typically.** ca
fe30: 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65  lled in response
fe40: 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f   to a user actio
fe50: 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69  n such as pressi
fe60: 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f  ng "Cancel".** o
fe70: 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74  r Ctrl-C where t
fe80: 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20  he user wants a 
fe90: 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61  long query opera
fea0: 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20  tion to halt.** 
feb0: 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a  immediately..**.
fec0: 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 74 6f  ** It is safe to
fed0: 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
fee0: 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
fef0: 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
ff00: 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
ff10: 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
ff20: 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
ff30: 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
ff40: 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
ff50: 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
ff60: 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
ff70: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
ff80: 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a  nection] that.**
ff90: 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
ffa0: 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
ffb0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
ffc0: 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
ffd0: 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f 70  .** If an SQL op
ffe0: 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
fff0: 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
10000 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
10010 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
10020 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
10030 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
10040 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
10050 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
10060 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
10070 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
10080 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
10090 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65  **.** An SQL ope
100a0 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69  ration that is i
100b0 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20  nterrupted will 
100c0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49  return [SQLITE_I
100d0 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66  NTERRUPT]..** If
100e0 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
100f0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
10100 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
10110 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
10120 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
10130 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
10140 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
10150 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
10160 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
10170 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
10180 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
10190 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
101a0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
101b0 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e  has no effect on
101c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
101d0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
101e0 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
101f0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
10200 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  turns..**.** INV
10210 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
10220 48 31 32 32 37 31 7d 20 54 68 65 20 5b 73 71 6c  H12271} The [sql
10230 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
10240 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
10250 20 66 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e 69   force all runni
10260 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53  ng.**          S
10270 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73  QL statements as
10280 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
10290 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
102a0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20  connection.**   
102b0 20 20 20 20 20 20 20 74 6f 20 68 61 6c 74 20 61         to halt a
102c0 66 74 65 72 20 70 72 6f 63 65 73 73 69 6e 67 20  fter processing 
102d0 61 74 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64 69  at most one addi
102e0 74 69 6f 6e 61 6c 20 72 6f 77 20 6f 66 20 64 61  tional row of da
102f0 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 37  ta..**.** {H1227
10300 32 7d 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65  2} Any SQL state
10310 6d 65 6e 74 20 74 68 61 74 20 69 73 20 69 6e 74  ment that is int
10320 65 72 72 75 70 74 65 64 20 62 79 20 5b 73 71 6c  errupted by [sql
10330 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
10340 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69  ].**          wi
10350 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
10360 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a  E_INTERRUPT]..**
10370 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
10380 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 37 39 7d 20  .**.** {A12279} 
10390 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
103a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
103b0 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
103c0 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
103d0 20 20 20 20 20 20 20 20 20 20 69 73 20 72 75 6e            is run
103e0 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68  ning then bad th
103f0 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  ings will likely
10400 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64   happen..*/.void
10410 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
10420 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  pt(sqlite3*);../
10430 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
10440 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
10450 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20  QL Statement Is 
10460 43 6f 6d 70 6c 65 74 65 20 7b 48 31 30 35 31 30  Complete {H10510
10470 7d 20 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70200>.**.**
10480 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
10490 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
104a0 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
104b0 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
104c0 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
104d0 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
104e0 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63 6f  seems to form co
104f0 6d 70 6c 65 74 65 20 61 20 53 51 4c 20 73 74 61  mplete a SQL sta
10500 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
10510 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
10520 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
10530 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
10540 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
10550 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
10560 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
10570 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74 68  eturn true if th
10580 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a  e input string.*
10590 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20  * appears to be 
105a0 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
105b0 74 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61  tatement.  A sta
105c0 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64  tement is judged
105d0 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65   to be.** comple
105e0 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69  te if it ends wi
105f0 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  th a semicolon t
10600 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20  oken and is not 
10610 61 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 61 0a  a fragment of a.
10620 2a 2a 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ** CREATE TRIGGE
10630 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53 65  R statement.  Se
10640 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
10650 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
10660 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
10670 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
10680 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
10690 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
106a0 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
106b0 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
106c0 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
106d0 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
106e0 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
106f0 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
10700 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
10710 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
10720 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ator..**.** Thes
10730 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
10740 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
10750 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
10760 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
10770 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
10780 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
10790 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
107a0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 31 7d  :.**.** {H10511}
107b0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 65 76   A successful ev
107c0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  aluation of [sql
107d0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
107e0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
107f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
10800 65 31 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e 73  e16()] functions
10810 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20   shall.**       
10820 20 20 20 72 65 74 75 72 6e 20 61 20 6e 75 6d 65     return a nume
10830 72 69 63 20 31 20 69 66 20 61 6e 64 20 6f 6e 6c  ric 1 if and onl
10840 79 20 69 66 20 74 68 65 20 6c 61 73 74 20 6e 6f  y if the last no
10850 6e 2d 77 68 69 74 65 73 70 61 63 65 0a 2a 2a 20  n-whitespace.** 
10860 20 20 20 20 20 20 20 20 20 74 6f 6b 65 6e 20 69           token i
10870 6e 20 74 68 65 69 72 20 69 6e 70 75 74 20 69 73  n their input is
10880 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68 61   a semicolon tha
10890 74 20 69 73 20 6e 6f 74 20 69 6e 20 62 65 74 77  t is not in betw
108a0 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  een.**          
108b0 74 68 65 20 42 45 47 49 4e 20 61 6e 64 20 45 4e  the BEGIN and EN
108c0 44 20 6f 66 20 61 20 43 52 45 41 54 45 20 54 52  D of a CREATE TR
108d0 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
108e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 32 7d 20  .**.** {H10512} 
108f0 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
10900 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
10910 75 72 73 20 64 75 72 69 6e 67 20 61 6e 20 69 6e  urs during an in
10920 76 6f 63 61 74 69 6f 6e 0a 2a 2a 20 20 20 20 20  vocation.**     
10930 20 20 20 20 20 6f 66 20 5b 73 71 6c 69 74 65 33       of [sqlite3
10940 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72 20  _complete()] or 
10950 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
10960 65 31 36 28 29 5d 20 74 68 65 6e 20 74 68 65 0a  e16()] then the.
10970 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75 74  **          rout
10980 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  ine shall return
10990 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
109a0 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f  .**.** ASSUMPTIO
109b0 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35 31  NS:.**.** {A1051
109c0 32 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  2} The input to 
109d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
109e0 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
109f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
10a00 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38  *          UTF-8
10a10 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
10a20 41 31 30 35 31 33 7d 20 54 68 65 20 69 6e 70 75  A10513} The inpu
10a30 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
10a40 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
10a50 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
10a60 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  nated.**        
10a70 20 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20    UTF-16 string 
10a80 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
10a90 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
10aa0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
10ab0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
10ac0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
10ad0 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
10ae0 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
10af0 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
10b00 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
10b10 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
10b20 55 53 59 20 45 72 72 6f 72 73 20 7b 48 31 32 33  USY Errors {H123
10b30 31 30 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a  10} <S40400>.**.
10b40 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
10b50 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
10b60 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69  function that mi
10b70 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
10b80 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
10b90 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
10ba0 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65   open a database
10bb0 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74   table that anot
10bc0 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
10bd0 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63   process has loc
10be0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ked..**.** If th
10bf0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
10c00 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
10c10 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
10c20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
10c30 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75  CKED].** is retu
10c40 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
10c50 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69   upon encounteri
10c60 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20  ng the lock. If 
10c70 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
10c80 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  k.** is not NULL
10c90 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  , then the callb
10ca0 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f  ack will be invo
10cb0 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
10cc0 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  uments..**.** Th
10cd0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10ce0 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72 20   to the handler 
10cf0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
10d00 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
10d10 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
10d20 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
10d30 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
10d40 6e 64 6c 65 72 28 29 2e 20 20 54 68 65 20 73 65  ndler().  The se
10d50 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
10d60 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
10d70 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
10d80 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
10d90 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
10da0 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
10db0 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  n invoked for th
10dc0 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  is locking event
10dd0 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 62 75 73  .  If the.** bus
10de0 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
10df0 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
10e00 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
10e10 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
10e20 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
10e30 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
10e40 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
10e50 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
10e60 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
10e70 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   If the callback
10e80 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
10e90 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
10ea0 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61  attempt.** is ma
10eb0 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  de to open the d
10ec0 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
10ed0 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ing and the cycl
10ee0 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
10ef0 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
10f00 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
10f10 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
10f20 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20  ee that it will 
10f30 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
10f40 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
10f50 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20   contention. If 
10f60 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
10f70 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
10f80 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
10f90 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
10fa0 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
10fb0 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
10fc0 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
10fd0 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20  ITE_BUSY].** or 
10fe0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
10ff0 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f  OCKED] instead o
11000 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  f invoking the b
11010 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
11020 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
11030 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
11040 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
11050 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
11060 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
11070 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
11080 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
11090 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
110a0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
110b0 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
110c0 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
110d0 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
110e0 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
110f0 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
11100 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
11110 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
11120 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
11130 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
11140 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
11150 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
11160 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
11170 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
11180 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
11190 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
111a0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
111b0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
111c0 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
111d0 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
111e0 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
111f0 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
11200 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
11210 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
11220 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
11230 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
11240 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
11250 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
11260 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
11270 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
11280 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
11290 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  proceed..**.** T
112a0 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
112b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
112c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ..**.** The [SQL
112d0 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20  ITE_BUSY] error 
112e0 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  is converted to 
112f0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
11300 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53  OCKED].** when S
11310 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20  QLite is in the 
11320 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67  middle of a larg
11330 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68  e transaction wh
11340 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63  ere all the.** c
11350 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20  hanges will not 
11360 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d  fit into the in-
11370 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53  memory cache.  S
11380 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c  QLite will.** al
11390 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53  ready hold a RES
113a0 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68  ERVED lock on th
113b0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
113c0 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a   but it needs.**
113d0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73   to promote this
113e0 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49   lock to EXCLUSI
113f0 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61  VE so that it ca
11400 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a  n spill cache.**
11410 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20   pages into the 
11420 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
11430 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f  thout harm to co
11440 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64  ncurrent.** read
11450 65 72 73 2e 20 20 49 66 20 69 74 20 69 73 20 75  ers.  If it is u
11460 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
11470 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
11480 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
11490 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
114a0 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
114b0 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
114c0 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
114d0 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
114e0 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
114f0 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
11500 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
11510 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
11520 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
11530 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 20 65  LOCKED].  This e
11540 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74  rror code promot
11550 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e  ion.** forces an
11560 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62   automatic rollb
11570 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67  ack of the chang
11580 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  es.  See the.** 
11590 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61  <a href="/cvstra
115a0 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74  c/wiki?p=Corrupt
115b0 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
115c0 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75  Error">.** Corru
115d0 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
115e0 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69  syError</a> wiki
115f0 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63   page for a disc
11600 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a  ussion of why.**
11610 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61   this is importa
11620 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  nt..**.** There 
11630 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
11640 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
11650 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
11660 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
11670 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
11680 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
11690 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
116a0 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
116b0 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 20 20  y set handler.  
116c0 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
116d0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
116e0 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
116f0 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
11700 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
11710 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  ndler..**.** INV
11720 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
11730 48 31 32 33 31 31 7d 20 54 68 65 20 5b 73 71 6c  H12311} The [sql
11740 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
11750 72 28 44 2c 43 2c 41 29 5d 20 66 75 6e 63 74 69  r(D,C,A)] functi
11760 6f 6e 20 73 68 61 6c 6c 20 72 65 70 6c 61 63 65  on shall replace
11770 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75 73  .**          bus
11780 79 20 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68  y callback in th
11790 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
117a0 65 63 74 69 6f 6e 5d 20 44 20 77 69 74 68 20 61  ection] D with a
117b0 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20   new.**         
117c0 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
117d0 6c 65 72 20 43 20 61 6e 64 20 61 70 70 6c 69 63  ler C and applic
117e0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
117f0 65 72 20 41 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  er A..**.** {H12
11800 33 31 32 7d 20 4e 65 77 6c 79 20 63 72 65 61 74  312} Newly creat
11810 65 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ed [database con
11820 6e 65 63 74 69 6f 6e 73 5d 20 73 68 61 6c 6c 20  nections] shall 
11830 68 61 76 65 20 61 20 62 75 73 79 0a 2a 2a 20 20  have a busy.**  
11840 20 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20          handler 
11850 6f 66 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b  of NULL..**.** {
11860 48 31 32 33 31 34 7d 20 57 68 65 6e 20 74 77 6f  H12314} When two
11870 20 6f 72 20 6d 6f 72 65 20 5b 64 61 74 61 62 61   or more [databa
11880 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
11890 73 68 61 72 65 20 61 0a 2a 2a 20 20 20 20 20 20  share a.**      
118a0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61      [sqlite3_ena
118b0 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
118c0 20 7c 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d   | common cache]
118d0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
118e0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
118f0 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
11900 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 65  connection curre
11910 6e 74 6c 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ntly using.**   
11920 20 20 20 20 20 20 20 74 68 65 20 63 61 63 68 65         the cache
11930 20 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65   shall be invoke
11940 64 20 77 68 65 6e 20 74 68 65 20 63 61 63 68 65  d when the cache
11950 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f   encounters a lo
11960 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31  ck..**.** {H1231
11970 36 7d 20 49 66 20 61 20 62 75 73 79 20 68 61 6e  6} If a busy han
11980 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  dler callback re
11990 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e  turns zero, then
119a0 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
119b0 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20  rface.**        
119c0 20 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20    that provoked 
119d0 74 68 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  the locking even
119e0 74 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b  t shall return [
119f0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
11a00 0a 2a 2a 20 7b 48 31 32 33 31 38 7d 20 53 51 4c  .** {H12318} SQL
11a10 69 74 65 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65  ite shall invoke
11a20 73 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  s the busy handl
11a30 65 72 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  er with two argu
11a40 6d 65 6e 74 73 20 77 68 69 63 68 0a 2a 2a 20 20  ments which.**  
11a50 20 20 20 20 20 20 20 20 61 72 65 20 61 20 63 6f          are a co
11a60 70 79 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65  py of the pointe
11a70 72 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68  r supplied by th
11a80 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
11a90 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
11aa0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
11ab0 64 6c 65 72 28 29 5d 20 61 6e 64 20 61 20 63 6f  dler()] and a co
11ac0 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  unt of the numbe
11ad0 72 20 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20  r of prior.**   
11ae0 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f         invocatio
11af0 6e 73 20 6f 66 20 74 68 65 20 62 75 73 79 20 68  ns of the busy h
11b00 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 73  andler for the s
11b10 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  ame locking even
11b20 74 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54  t..**.** ASSUMPT
11b30 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  IONS:.**.** {A12
11b40 33 31 39 7d 20 41 20 62 75 73 79 20 68 61 6e 64  319} A busy hand
11b50 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
11b60 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
11b70 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20  connection.**   
11b80 20 20 20 20 20 20 20 6f 72 20 5b 70 72 65 70 61         or [prepa
11b90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
11ba0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
11bb0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f  busy handler..*/
11bc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
11bd0 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
11be0 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
11bf0 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  ,int), void*);..
11c00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11c10 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
11c20 75 74 20 7b 48 31 32 33 34 30 7d 20 3c 53 34 30  ut {H12340} <S40
11c30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  410>.**.** This 
11c40 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
11c50 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
11c60 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
11c70 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73  ler] that sleeps
11c80 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66  .** for a specif
11c90 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ied amount of ti
11ca0 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20  me when a table 
11cb0 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20  is locked.  The 
11cc0 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
11cd0 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
11ce0 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
11cf0 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
11d00 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
11d10 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
11d20 6c 61 74 65 64 2e 20 7b 48 31 32 33 34 33 7d 20  lated. {H12343} 
11d30 41 66 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69  After "ms" milli
11d40 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
11d50 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
11d60 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
11d70 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
11d80 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
11d90 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
11da0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
11db0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
11dc0 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20  ..**.** Calling 
11dd0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
11de0 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
11df0 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
11e00 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
11e10 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
11e20 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54  andlers..**.** T
11e30 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
11e40 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
11e50 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72  andler for a par
11e60 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
11e70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11e80 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d   any any given m
11e90 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68  oment.  If anoth
11ea0 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a  er busy handler.
11eb0 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20  ** was defined  
11ec0 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  (using [sqlite3_
11ed0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29  busy_handler()])
11ee0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
11ef0 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  g.** this routin
11f00 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75  e, that other bu
11f10 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
11f20 65 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  eared..**.** INV
11f30 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
11f40 48 31 32 33 34 31 7d 20 54 68 65 20 5b 73 71 6c  H12341} The [sql
11f50 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
11f60 74 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68  t()] function sh
11f70 61 6c 6c 20 6f 76 65 72 72 69 64 65 20 61 6e 79  all override any
11f80 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20   prior.**       
11f90 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79     [sqlite3_busy
11fa0 5f 74 69 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b  _timeout()] or [
11fb0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
11fc0 64 6c 65 72 28 29 5d 20 73 65 74 74 69 6e 67 0a  dler()] setting.
11fd0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74  **          on t
11fe0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
11ff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
12000 2a 0a 2a 2a 20 7b 48 31 32 33 34 33 7d 20 49 66  *.** {H12343} If
12010 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
12020 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
12030 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69  usy_timeout()] i
12040 73 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20  s less than.**  
12050 20 20 20 20 20 20 20 20 6f 72 20 65 71 75 61 6c          or equal
12060 20 74 6f 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74   to zero, then t
12070 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
12080 73 68 61 6c 6c 20 62 65 20 63 6c 65 61 72 65 64  shall be cleared
12090 20 73 6f 20 74 68 61 74 0a 2a 2a 20 20 20 20 20   so that.**     
120a0 20 20 20 20 20 61 6c 6c 20 73 75 62 73 65 71 75       all subsequ
120b0 65 6e 74 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  ent locking even
120c0 74 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 72  ts immediately r
120d0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
120e0 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  SY]..**.** {H123
120f0 34 34 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70  44} If the 2nd p
12100 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
12110 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
12120 74 28 29 5d 20 69 73 20 61 20 70 6f 73 69 74 69  t()] is a positi
12130 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  ve.**          n
12140 75 6d 62 65 72 20 4e 2c 20 74 68 65 6e 20 61 20  umber N, then a 
12150 62 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61  busy handler sha
12160 6c 6c 20 62 65 20 73 65 74 20 74 68 61 74 20 72  ll be set that r
12170 65 70 65 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a  epeatedly calls.
12180 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
12190 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
121a0 69 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  in the [sqlite3_
121b0 76 66 73 20 7c 20 56 46 53 20 69 6e 74 65 72 66  vfs | VFS interf
121c0 61 63 65 5d 20 75 6e 74 69 6c 0a 2a 2a 20 20 20  ace] until.**   
121d0 20 20 20 20 20 20 20 65 69 74 68 65 72 20 74 68         either th
121e0 65 20 6c 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72  e lock clears or
121f0 20 75 6e 74 69 6c 20 74 68 65 20 63 75 6d 75 6c   until the cumul
12200 61 74 69 76 65 20 73 6c 65 65 70 20 74 69 6d 65  ative sleep time
12210 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 70  .**          rep
12220 6f 72 74 65 64 20 62 61 63 6b 20 62 79 20 78 53  orted back by xS
12230 6c 65 65 70 28 29 20 65 78 63 65 65 64 73 20 4e  leep() exceeds N
12240 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a   milliseconds..*
12250 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
12260 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
12270 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
12280 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
12290 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
122a0 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
122b0 51 75 65 72 69 65 73 20 7b 48 31 32 33 37 30 7d  Queries {H12370}
122c0 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10000>.**.** 
122d0 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62  Definition: A <b
122e0 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62  >result table</b
122f0 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61  > is memory data
12300 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74   structure creat
12310 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71  ed by the.** [sq
12320 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
12330 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41  )] interface.  A
12340 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65   result table re
12350 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d  cords the.** com
12360 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75  plete query resu
12370 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20  lts from one or 
12380 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a  more queries..**
12390 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f  .** The table co
123a0 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61  nceptually has a
123b0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
123c0 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75  and columns.  Bu
123d0 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65  t.** these numbe
123e0 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20  rs are not part 
123f0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
12400 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65  ble itself.  The
12410 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72  se.** numbers ar
12420 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72  e obtained separ
12430 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65  ately.  Let N be
12440 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
12450 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20  ows.** and M be 
12460 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
12470 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  lumns..**.** A r
12480 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61  esult table is a
12490 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
124a0 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
124b0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
124c0 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61  ings..** There a
124d0 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65  re (N+1)*M eleme
124e0 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79  nts in the array
124f0 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70  .  The first M p
12500 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a  ointers point.**
12510 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
12520 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
12530 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61    contain the na
12540 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  mes of the colum
12550 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  ns..** The remai
12560 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c  ning entries all
12570 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20   point to query 
12580 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76  results.  NULL v
12590 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20  alues result.** 
125a0 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  in NULL pointers
125b0 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  .  All other val
125c0 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72  ues are in their
125d0 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
125e0 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
125f0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
12600 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  as returned by [
12610 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
12620 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20  ext()]..**.** A 
12630 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67  result table mig
12640 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e  ht consist of on
12650 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79  e or more memory
12660 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a   allocations..**
12670 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
12680 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74  to pass a result
12690 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20   table directly 
126a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
126b0 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ()]..** A result
126c0 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65   table should be
126d0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69   deallocated usi
126e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
126f0 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _table()]..**.**
12700 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   As an example o
12710 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
12720 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
12730 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
12740 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
12750 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
12760 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
12770 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
12780 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
12790 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
127a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
127b0 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
127c0 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
127d0 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
127e0 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
127f0 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
12800 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
12810 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
12820 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
12830 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
12840 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
12850 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
12860 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
12870 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
12880 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
12890 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
128a0 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
128b0 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
128c0 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
128d0 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
128e0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
128f0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
12900 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
12910 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
12920 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
12930 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
12940 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
12950 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
12960 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
12970 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
12980 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
12990 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
129a0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
129b0 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
129c0 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
129d0 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
129e0 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
129f0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
12a00 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
12a10 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
12a20 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e>.**.** The sql
12a30 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
12a40 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
12a50 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
12a60 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
12a70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
12a80 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
12a90 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
12aa0 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
12ab0 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
12ac0 72 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 61  r.  It returns a
12ad0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
12ae0 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
12af0 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
12b00 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
12b10 2a 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c  * After the call
12b20 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73  ing function has
12b30 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
12b40 74 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73  the result, it s
12b50 68 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68  hould.** pass th
12b60 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
12b70 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
12b80 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
12b90 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
12ba0 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
12bb0 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
12bc0 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
12bd0 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
12be0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
12bf0 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
12c00 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
12c10 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
12c20 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
12c30 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
12c40 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
12c50 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
12c60 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
12c70 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
12c80 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
12c90 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
12ca0 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
12cb0 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
12cc0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
12cd0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
12ce0 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
12cf0 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
12d00 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
12d10 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
12d20 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
12d30 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
12d40 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
12d50 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
12d60 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
12d70 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
12d80 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
12d90 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
12da0 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
12db0 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
12dc0 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
12dd0 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
12de0 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
12df0 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
12e00 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
12e10 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
12e20 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
12e30 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
12e40 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
12e50 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73  errcode()] or [s
12e60 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
12e70 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
12e80 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37  TS:.**.** {H1237
12e90 31 7d 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33  1} If a [sqlite3
12ea0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61  _get_table()] fa
12eb0 69 6c 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  ils a memory all
12ec0 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a  ocation, then.**
12ed0 20 20 20 20 20 20 20 20 20 20 69 74 20 73 68 61            it sha
12ee0 6c 6c 20 66 72 65 65 20 74 68 65 20 72 65 73 75  ll free the resu
12ef0 6c 74 20 74 61 62 6c 65 20 75 6e 64 65 72 20 63  lt table under c
12f00 6f 6e 73 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f  onstruction, abo
12f10 72 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  rt the.**       
12f20 20 20 20 71 75 65 72 79 20 69 6e 20 70 72 6f 63     query in proc
12f30 65 73 73 2c 20 73 6b 69 70 20 61 6e 79 20 73 75  ess, skip any su
12f40 62 73 65 71 75 65 6e 74 20 71 75 65 72 69 65 73  bsequent queries
12f50 2c 20 73 65 74 20 74 68 65 0a 2a 2a 20 20 20 20  , set the.**    
12f60 20 20 20 20 20 20 2a 70 61 7a 52 65 73 75 6c 74        *pazResult
12f70 20 6f 75 74 70 75 74 20 70 6f 69 6e 74 65 72 20   output pointer 
12f80 74 6f 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75  to NULL and retu
12f90 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  rn [SQLITE_NOMEM
12fa0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 33  ]..**.** {H12373
12fb0 7d 20 49 66 20 74 68 65 20 70 6e 43 6f 6c 75 6d  } If the pnColum
12fc0 6e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  n parameter to [
12fd0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
12fe0 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  e()] is not NULL
12ff0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
13000 6e 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 69  n a successful i
13010 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
13020 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
13030 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20  )] shall.**     
13040 20 20 20 20 20 77 72 69 74 65 20 74 68 65 20 6e       write the n
13050 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
13060 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
13070 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f      result set o
13080 66 20 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f  f the query into
13090 20 2a 70 6e 43 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a   *pnColumn..**.*
130a0 2a 20 7b 48 31 32 33 37 34 7d 20 49 66 20 74 68  * {H12374} If th
130b0 65 20 70 6e 52 6f 77 20 70 61 72 61 6d 65 74 65  e pnRow paramete
130c0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65  r to [sqlite3_ge
130d0 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f  t_table()] is no
130e0 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20  t NULL.**       
130f0 20 20 20 74 68 65 6e 20 61 20 73 75 63 63 65 73     then a succes
13100 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
13110 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  of [sqlite3_get_
13120 74 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a  table()] shall.*
13130 2a 20 20 20 20 20 20 20 20 20 20 77 72 69 74 65  *          write
13140 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
13150 72 6f 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20  rows in the.**  
13160 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73          result s
13170 65 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  et of the query 
13180 69 6e 74 6f 20 2a 70 6e 52 6f 77 2e 0a 2a 2a 0a  into *pnRow..**.
13190 2a 2a 20 7b 48 31 32 33 37 36 7d 20 41 20 73 75  ** {H12376} A su
131a0 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
131b0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
131c0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 74 68 61  get_table()] tha
131d0 74 20 63 6f 6d 70 75 74 65 73 0a 2a 2a 20 20 20  t computes.**   
131e0 20 20 20 20 20 20 20 4e 20 72 6f 77 73 20 6f 66         N rows of
131f0 20 72 65 73 75 6c 74 20 77 69 74 68 20 43 20 63   result with C c
13200 6f 6c 75 6d 6e 73 20 70 65 72 20 72 6f 77 20 73  olumns per row s
13210 68 61 6c 6c 20 6d 61 6b 65 20 2a 70 61 7a 52 65  hall make *pazRe
13220 73 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  sult.**         
13230 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 72 72   point to an arr
13240 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
13250 6f 20 28 4e 2b 31 29 2a 43 20 73 74 72 69 6e 67  o (N+1)*C string
13260 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73  s where the firs
13270 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 20  t.**          C 
13280 73 74 72 69 6e 67 73 20 61 72 65 20 63 6f 6c 75  strings are colu
13290 6d 6e 20 6e 61 6d 65 73 20 61 73 20 6f 62 74 61  mn names as obta
132a0 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 20 20 20  ined from.**    
132b0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
132c0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e  olumn_name()] an
132d0 64 20 74 68 65 20 72 65 73 74 20 61 72 65 20 63  d the rest are c
132e0 6f 6c 75 6d 6e 20 72 65 73 75 6c 74 20 76 61 6c  olumn result val
132f0 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ues.**          
13300 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
13310 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
13320 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  xt()]..**.** {H1
13330 32 33 37 39 7d 20 54 68 65 20 76 61 6c 75 65 73  2379} The values
13340 20 69 6e 20 74 68 65 20 70 61 7a 52 65 73 75 6c   in the pazResul
13350 74 20 61 72 72 61 79 20 72 65 74 75 72 6e 65 64  t array returned
13360 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   by [sqlite3_get
13370 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20  _table()].**    
13380 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 6d 61        shall rema
13390 69 6e 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 63  in valid until c
133a0 6c 65 61 72 65 64 20 62 79 20 5b 73 71 6c 69 74  leared by [sqlit
133b0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
133c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 38 32 7d  ..**.** {H12382}
133d0 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f   When an error o
133e0 63 63 75 72 73 20 64 75 72 69 6e 67 20 65 76 61  ccurs during eva
133f0 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  luation of [sqli
13400 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
13410 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
13420 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
13430 73 65 74 20 2a 70 61 7a 52 65 73 75 6c 74 20 74  set *pazResult t
13440 6f 20 4e 55 4c 4c 2c 20 77 72 69 74 65 20 61 6e  o NULL, write an
13450 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
13460 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 6f 20  *          into 
13470 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
13480 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
13490 6c 6c 6f 63 28 29 5d 2c 20 6d 61 6b 65 0a 2a 2a  lloc()], make.**
134a0 20 20 20 20 20 20 20 20 20 20 2a 2a 70 7a 45 72            **pzEr
134b0 72 6d 73 67 20 70 6f 69 6e 74 20 74 6f 20 74 68  rmsg point to th
134c0 61 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  at error message
134d0 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 61 0a 2a  , and return a.*
134e0 2a 20 20 20 20 20 20 20 20 20 20 61 70 70 72 6f  *          appro
134f0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
13500 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  de]..*/.int sqli
13510 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
13520 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
13530 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
13540 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
13550 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
13560 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
13570 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
13580 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
13590 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
135a0 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
135b0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
135c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
135d0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
135e0 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
135f0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
13600 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
13610 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
13620 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
13630 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
13640 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
13650 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
13660 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
13670 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
13680 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
13690 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
136a0 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
136b0 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
136c0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31  ng Functions {H1
136d0 37 34 30 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53  7400} <S70000><S
136e0 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20000>.**.** The
136f0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
13700 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68  workalikes of th
13710 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
13720 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
13730 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
13740 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
13750 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
13760 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
13770 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
13780 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
13790 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
137a0 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
137b0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
137c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
137d0 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
137e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
137f0 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
13800 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
13810 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
13820 33 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68  3_free()].  Both
13830 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
13840 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
13850 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
13860 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
13870 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
13880 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
13890 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
138a0 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
138b0 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73  .** In sqlite3_s
138c0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
138d0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
138e0 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
138f0 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
13900 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
13910 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
13920 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
13930 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
13940 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
13950 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
13960 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
13970 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
13980 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
13990 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
139a0 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
139b0 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
139c0 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
139d0 6e 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20  ntf().  This is 
139e0 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
139f0 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
13a00 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
13a10 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
13a20 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
13a30 70 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74  patibility.  Not
13a40 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
13a50 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
13a60 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
13a70 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
13a80 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
13a90 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
13aa0 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
13ab0 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
13ac0 68 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61  he buffer.  We a
13ad0 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
13ae0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
13af0 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
13b00 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
13b10 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
13b20 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
13b30 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
13b40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
13b50 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
13b60 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
13b70 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
13b80 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
13b90 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
13ba0 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
13bb0 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
13bc0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
13bd0 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
13be0 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
13bf0 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
13c00 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68  -terminated.  Th
13c10 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
13c20 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
13c30 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
13c40 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
13c50 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
13c60 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
13c70 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
13c80 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
13c90 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
13ca0 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
13cb0 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
13cc0 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  cters..**.** The
13cd0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
13ce0 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
13cf0 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
13d00 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
13d10 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
13d20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
13d30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
13d40 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
13d50 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
13d60 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
13d70 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
13d80 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
13d90 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
13da0 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  , and "%z" optio
13db0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71  ns..**.** The %q
13dc0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
13dd0 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
13de0 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
13df0 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ull-terminated.*
13e00 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
13e10 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
13e20 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
13e30 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
13e40 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
13e50 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
13e60 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
13e70 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20  tring literal.  
13e80 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
13e90 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
13ea0 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
13eb0 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
13ec0 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
13ed0 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
13ee0 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
13ef0 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
13f00 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
13f10 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
13f20 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
13f30 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
13f40 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
13f50 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
13f60 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
13f70 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
13f80 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
13f90 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
13fa0 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
13fb0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
13fc0 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
13fd0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
13fe0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
13ff0 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
14000 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
14010 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
14020 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
14030 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
14040 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
14050 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
14060 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
14070 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
14080 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
14090 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
140a0 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
140b0 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
140c0 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
140d0 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
140e0 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
140f0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
14100 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
14110 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
14120 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
14130 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
14140 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
14150 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
14160 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
14170 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
14180 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
14190 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
141a0 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
141b0 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
141c0 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
141d0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
141e0 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
141f0 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
14200 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
14210 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
14220 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
14230 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
14240 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
14250 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
14260 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
14270 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
14280 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
14290 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
142a0 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
142b0 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
142c0 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  iteral..**.** Th
142d0 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
142e0 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
142f0 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
14300 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
14310 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
14320 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
14330 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  tring.  Addition
14340 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72  ally, if the par
14350 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a  ameter in the.**
14360 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69   argument list i
14370 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
14380 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73  , %Q substitutes
14390 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22   the text "NULL"
143a0 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e   (without.** sin
143b0 67 6c 65 20 71 75 6f 74 65 73 29 20 69 6e 20 70  gle quotes) in p
143c0 6c 61 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f  lace of the %Q o
143d0 70 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20  ption.  So, for 
143e0 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
143f0 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
14400 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
14410 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
14420 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
14430 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
14440 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
14450 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
14460 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
14470 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
14480 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
14490 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
144a0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
144b0 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
144c0 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
144d0 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
144e0 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
144f0 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
14500 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
14510 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
14520 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
14530 2a 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  * The "%z" forma
14540 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
14550 6b 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20  ks exactly like 
14560 22 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a  "%s" with the.**
14570 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
14580 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
14590 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
145a0 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
145b0 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
145c0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
145d0 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
145e0 6e 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e  nput string. {EN
145f0 44 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  D}.**.** INVARIA
14600 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34  NTS:.**.** {H174
14610 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  03}  The [sqlite
14620 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e 64  3_mprintf()] and
14630 20 5b 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   [sqlite3_vmprin
14640 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  tf()] interfaces
14650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
14660 74 75 72 6e 20 65 69 74 68 65 72 20 70 6f 69 6e  turn either poin
14670 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
14680 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
14690 72 69 6e 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a  rings held in.**
146a0 20 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72             memor
146b0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
146c0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
146d0 29 5d 20 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74  )] or NULL point
146e0 65 72 73 20 69 66 0a 2a 2a 20 20 20 20 20 20 20  ers if.**       
146f0 20 20 20 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73      a call to [s
14700 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
14710 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48   fails..**.** {H
14720 31 37 34 30 36 7d 20 20 54 68 65 20 5b 73 71 6c  17406}  The [sql
14730 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
14740 20 69 6e 74 65 72 66 61 63 65 20 77 72 69 74 65   interface write
14750 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
14760 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
14770 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e   UTF-8 string in
14780 74 6f 20 74 68 65 20 62 75 66 66 65 72 20 70 6f  to the buffer po
14790 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
147a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
147b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 70 72  .**           pr
147c0 6f 76 69 64 65 64 20 74 68 61 74 20 74 68 65 20  ovided that the 
147d0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
147e0 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
147f0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  zero..**.** {H17
14800 34 30 37 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  407}  The [sqlit
14810 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
14820 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
14830 74 20 77 72 69 74 65 20 73 6c 6f 74 73 20 6f 66  t write slots of
14840 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74  .**           it
14850 73 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  s output buffer 
14860 28 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  (the second para
14870 6d 65 74 65 72 29 20 6f 75 74 73 69 64 65 20 74  meter) outside t
14880 68 65 20 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20  he range.**     
14890 20 20 20 20 20 20 6f 66 20 30 20 74 68 72 6f 75        of 0 throu
148a0 67 68 20 4e 2d 31 20 28 77 68 65 72 65 20 4e 20  gh N-1 (where N 
148b0 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
148c0 61 6d 65 74 65 72 29 0a 2a 2a 20 20 20 20 20 20  ameter).**      
148d0 20 20 20 20 20 72 65 67 61 72 64 6c 65 73 73 20       regardless 
148e0 6f 66 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  of the length of
148f0 20 74 68 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20   the string.**  
14900 20 20 20 20 20 20 20 20 20 72 65 71 75 65 73 74           request
14910 65 64 20 62 79 20 74 68 65 20 66 6f 72 6d 61 74  ed by the format
14920 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a   specification..
14930 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
14940 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
14950 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
14960 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
14970 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
14980 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
14990 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
149a0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
149b0 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  char*, ...);../*
149c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
149d0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
149e0 53 75 62 73 79 73 74 65 6d 20 7b 48 31 37 33 30  Subsystem {H1730
149f0 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a  0} <S20000>.**.*
14a00 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
14a10 65 20 20 75 73 65 73 20 74 68 65 73 65 20 74 68  e  uses these th
14a20 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
14a30 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
14a40 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
14a50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
14a60 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
14a70 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
14a80 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
14a90 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
14aa0 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
14ab0 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
14ac0 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
14ad0 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
14ae0 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
14af0 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
14b00 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
14b10 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
14b20 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
14b30 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
14b40 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
14b50 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
14b60 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
14b70 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
14b80 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
14b90 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33  r..** If sqlite3
14ba0 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
14bb0 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
14bc0 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
14bd0 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
14be0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
14bf0 65 72 2e 20 20 49 66 20 74 68 65 20 70 61 72 61  er.  If the para
14c00 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
14c10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
14c20 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
14c30 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
14c40 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
14c50 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
14c60 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e  er..**.** Callin
14c70 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
14c80 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
14c90 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
14ca0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
14cb0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
14cc0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
14cd0 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
14ce0 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
14cf0 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
14d00 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ed.  The sqlite3
14d10 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
14d20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
14d30 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
14d40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
14d50 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
14d60 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
14d70 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
14d80 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
14d90 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
14da0 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
14db0 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
14dc0 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
14dd0 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
14de0 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
14df0 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
14e00 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
14e10 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
14e20 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
14e30 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
14e40 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
14e50 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
14e60 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
14e70 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
14e80 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
14e90 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
14ea0 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
14eb0 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
14ec0 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
14ed0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
14ee0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
14ef0 5f 66 72 65 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  _free()..**.** T
14f00 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
14f10 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  oc() interface a
14f20 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a  ttempts to resiz
14f30 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d  e a.** prior mem
14f40 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
14f50 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20  o be at least N 
14f60 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69  bytes, where N i
14f70 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20  s the.** second 
14f80 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20  parameter.  The 
14f90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14fa0 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20  n to be resized 
14fb0 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
14fc0 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 20 74  parameter.  If t
14fd0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
14fe0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
14ff0 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20  alloc().** is a 
15000 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
15010 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
15020 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
15030 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
15040 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72  3_malloc(N) wher
15050 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
15060 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
15070 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
15080 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 65 63 6f  ..** If the seco
15090 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
150a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
150b0 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
150c0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
150d0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
150e0 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
150f0 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
15100 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65  ite3_free(P) whe
15110 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73  re P is the firs
15120 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
15130 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
15140 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61  ..** sqlite3_rea
15150 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61  lloc() returns a
15160 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
15170 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
15180 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
15190 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
151a0 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63  r NULL if suffic
151b0 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75  ient memory is u
151c0 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49  navailable..** I
151d0 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20  f M is the size 
151e0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
151f0 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69  ocation, then mi
15200 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20  n(N,M) bytes.** 
15210 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
15220 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69  ocation are copi
15230 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69  ed into the begi
15240 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20  nning of buffer 
15250 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
15260 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
15270 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
15280 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
15290 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65  ed..** If sqlite
152a0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
152b0 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  rns NULL, then t
152c0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
152d0 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72  ion.** is not fr
152e0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  eed..**.** The m
152f0 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
15300 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
15310 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
15320 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
15330 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
15340 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
15350 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 7b 45  yte boundary. {E
15360 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  ND}.**.** The de
15370 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65 6e 74 61  fault implementa
15380 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d 65 6d 6f  tion of the memo
15390 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
153a0 62 73 79 73 74 65 6d 20 75 73 65 73 0a 2a 2a 20  bsystem uses.** 
153b0 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65  the malloc(), re
153c0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
153d0 28 29 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  () provided by t
153e0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
153f0 62 72 61 72 79 2e 0a 2a 2a 20 7b 48 31 37 33 38  brary..** {H1738
15400 32 7d 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53  2} However, if S
15410 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
15420 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
15430 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45  LITE_MEMORY_SIZE
15440 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72  =<i>NNN</i> C pr
15450 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
15460 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f   (where <i>NNN</
15470 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65  i>.** is an inte
15480 67 65 72 29 2c 20 74 68 65 6e 20 53 51 4c 69 74  ger), then SQLit
15490 65 20 63 72 65 61 74 65 20 61 20 73 74 61 74 69  e create a stati
154a0 63 20 61 72 72 61 79 20 6f 66 20 61 74 20 6c 65  c array of at le
154b0 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69  ast.** <i>NNN</i
154c0 3e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  > bytes in size 
154d0 61 6e 64 20 75 73 65 73 20 74 68 61 74 20 61 72  and uses that ar
154e0 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  ray for all of i
154f0 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65  ts dynamic.** me
15500 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
15510 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20 20 41 64  needs. {END}  Ad
15520 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20  ditional memory 
15530 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74 69 6f 6e  allocator option
15540 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61 64 64 65  s.** may be adde
15550 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
15560 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  ases..**.** In S
15570 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
15580 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
15590 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
155a0 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
155b0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
155c0 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
155d0 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
155e0 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
155f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
15600 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
15610 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
15620 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
15630 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
15640 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
15650 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
15660 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
15670 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  be used..**.** T
15680 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
15690 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
156a0 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  lls.** the syste
156b0 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
156c0 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
156d0 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
156e0 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
156f0 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
15700 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
15710 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
15720 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
15730 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
15740 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
15750 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
15760 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
15770 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
15780 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65  rors are detecte
15790 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61  d, but.** they a
157a0 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
157b0 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
157c0 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
157d0 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
157e0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
157f0 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  OMEM]..**.** INV
15800 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
15810 48 31 37 33 30 33 7d 20 20 54 68 65 20 5b 73 71  H17303}  The [sq
15820 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d  lite3_malloc(N)]
15830 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
15840 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e  ns either a poin
15850 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ter to.**       
15860 20 20 20 20 61 20 6e 65 77 6c 79 20 63 68 65 63      a newly chec
15870 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b 20 6f 66  ked-out block of
15880 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
15890 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20  s of memory.**  
158a0 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73           that is
158b0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c   8-byte aligned,
158c0 20 6f 72 20 69 74 20 72 65 74 75 72 6e 73 20 4e   or it returns N
158d0 55 4c 4c 20 69 66 20 69 74 20 69 73 20 75 6e 61  ULL if it is una
158e0 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ble.**          
158f0 20 74 6f 20 66 75 6c 66 69 6c 6c 20 74 68 65 20   to fulfill the 
15900 72 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a 2a 20 7b  request..**.** {
15910 48 31 37 33 30 34 7d 20 20 54 68 65 20 5b 73 71  H17304}  The [sq
15920 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d  lite3_malloc(N)]
15930 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
15940 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
15950 72 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  r if.**         
15960 20 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e    N is less than
15970 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
15980 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 35  o..**.** {H17305
15990 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  }  The [sqlite3_
159a0 66 72 65 65 28 50 29 5d 20 69 6e 74 65 72 66 61  free(P)] interfa
159b0 63 65 20 72 65 6c 65 61 73 65 73 20 6d 65 6d 6f  ce releases memo
159c0 72 79 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a  ry previously.**
159d0 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72             retur
159e0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
159f0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
15a00 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
15a10 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
15a20 20 6d 61 6b 69 6e 67 20 69 74 20 61 76 61 69 6c   making it avail
15a30 61 62 6c 65 20 66 6f 72 20 72 65 75 73 65 2e 0a  able for reuse..
15a40 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 36 7d 20 20  **.** {H17306}  
15a50 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  A call to [sqlit
15a60 65 33 5f 66 72 65 65 28 4e 55 4c 4c 29 5d 20 69  e3_free(NULL)] i
15a70 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
15a80 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31  op..**.** {H1731
15a90 30 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73  0}  A call to [s
15aa0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 30  qlite3_realloc(0
15ab0 2c 4e 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65  ,N)] is equivale
15ac0 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20  nt to a call.** 
15ad0 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71            to [sq
15ae0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 5d  lite3_malloc(N)]
15af0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 32 7d  ..**.** {H17312}
15b00 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c    A call to [sql
15b10 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 30  ite3_realloc(P,0
15b20 29 5d 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  )] is equivalent
15b30 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a 20 20 20   to a call.**   
15b40 20 20 20 20 20 20 20 20 74 6f 20 5b 73 71 6c 69          to [sqli
15b50 74 65 33 5f 66 72 65 65 28 50 29 5d 2e 0a 2a 2a  te3_free(P)]..**
15b60 0a 2a 2a 20 7b 48 31 37 33 31 35 7d 20 20 54 68  .** {H17315}  Th
15b70 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
15b80 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  es [sqlite3_mall
15b90 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
15ba0 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20  realloc()],.**  
15bb0 20 20 20 20 20 20 20 20 20 61 6e 64 20 5b 73 71           and [sq
15bc0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 66 6f  lite3_free()] fo
15bd0 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6d 65 6d  r all of its mem
15be0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ory allocation a
15bf0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  nd.**           
15c00 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  deallocation nee
15c10 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31  ds..**.** {H1731
15c20 38 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  8}  The [sqlite3
15c30 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 69  _realloc(P,N)] i
15c40 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
15c50 20 65 69 74 68 65 72 20 61 20 70 6f 69 6e 74 65   either a pointe
15c60 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  r.**           t
15c70 6f 20 61 20 62 6c 6f 63 6b 20 6f 66 20 63 68 65  o a block of che
15c80 63 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f 72 79 20  cked-out memory 
15c90 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
15ca0 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20 20  tes in size.**  
15cb0 20 20 20 20 20 20 20 20 20 74 68 61 74 20 69 73           that is
15cc0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 2c   8-byte aligned,
15cd0 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
15ce0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32  er..**.** {H1732
15cf0 31 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65  1}  When [sqlite
15d00 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20  3_realloc(P,N)] 
15d10 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55  returns a non-NU
15d20 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66  LL pointer, it f
15d30 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  irst.**         
15d40 20 20 63 6f 70 69 65 73 20 74 68 65 20 66 69 72    copies the fir
15d50 73 74 20 4b 20 62 79 74 65 73 20 6f 66 20 63 6f  st K bytes of co
15d60 6e 74 65 6e 74 20 66 72 6f 6d 20 50 20 69 6e 74  ntent from P int
15d70 6f 20 74 68 65 20 6e 65 77 6c 79 0a 2a 2a 20 20  o the newly.**  
15d80 20 20 20 20 20 20 20 20 20 61 6c 6c 6f 63 61 74           allocat
15d90 65 64 20 62 6c 6f 63 6b 2c 20 77 68 65 72 65 20  ed block, where 
15da0 4b 20 69 73 20 74 68 65 20 6c 65 73 73 65 72 20  K is the lesser 
15db0 6f 66 20 4e 20 61 6e 64 20 74 68 65 20 73 69 7a  of N and the siz
15dc0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20  e of.**         
15dd0 20 20 74 68 65 20 62 75 66 66 65 72 20 50 2e 0a    the buffer P..
15de0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 32 7d 20 20  **.** {H17322}  
15df0 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  When [sqlite3_re
15e00 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75  alloc(P,N)] retu
15e10 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  rns a non-NULL p
15e20 6f 69 6e 74 65 72 2c 20 69 74 20 66 69 72 73 74  ointer, it first
15e30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
15e40 6c 65 61 73 65 73 20 74 68 65 20 62 75 66 66 65  leases the buffe
15e50 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  r P..**.** {H173
15e60 32 33 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74  23}  When [sqlit
15e70 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d  e3_realloc(P,N)]
15e80 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74   returns NULL, t
15e90 68 65 20 62 75 66 66 65 72 20 50 20 69 73 0a 2a  he buffer P is.*
15ea0 2a 20 20 20 20 20 20 20 20 20 20 20 6e 6f 74 20  *           not 
15eb0 6d 6f 64 69 66 69 65 64 20 6f 72 20 72 65 6c 65  modified or rele
15ec0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55  ased..**.** ASSU
15ed0 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b  MPTIONS:.**.** {
15ee0 41 31 37 33 35 30 7d 20 20 54 68 65 20 70 6f 69  A17350}  The poi
15ef0 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
15f00 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
15f10 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
15f20 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 20 20  realloc()].**   
15f30 20 20 20 20 20 20 20 20 6d 75 73 74 20 62 65 20          must be 
15f40 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65  either NULL or e
15f50 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74  lse pointers obt
15f60 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
15f70 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
15f80 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
15f90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
15fa0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
15fb0 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
15fc0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e  e.**           n
15fd0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
15fe0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 37  ased..**.** {A17
15ff0 33 35 31 7d 20 20 54 68 65 20 61 70 70 6c 69 63  351}  The applic
16000 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72  ation must not r
16010 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79  ead or write any
16020 20 70 61 72 74 20 6f 66 0a 2a 2a 20 20 20 20 20   part of.**     
16030 20 20 20 20 20 20 61 20 62 6c 6f 63 6b 20 6f 66        a block of
16040 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
16050 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
16060 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20  ed using.**     
16070 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 66        [sqlite3_f
16080 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
16090 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
160a0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
160b0 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
160c0 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
160d0 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
160e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
160f0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
16100 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
16110 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
16120 69 73 74 69 63 73 20 7b 48 31 37 33 37 30 7d 20  istics {H17370} 
16130 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53  <S30210>.**.** S
16140 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
16150 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
16160 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
16170 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
16180 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
16190 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
161a0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
161b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
161c0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
161d0 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
161e0 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
161f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
16200 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
16210 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
16220 2a 20 7b 48 31 37 33 37 31 7d 20 54 68 65 20 5b  * {H17371} The [
16230 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
16240 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  sed()] routine r
16250 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
16260 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 20 20  r of bytes.**   
16270 20 20 20 20 20 20 20 6f 66 20 6d 65 6d 6f 72 79         of memory
16280 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
16290 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
162a0 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
162b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 33 7d 20  .**.** {H17373} 
162c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
162d0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
162e0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
162f0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
16300 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f           value o
16310 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
16320 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
16330 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
16340 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ark.**          
16350 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 0a  was last reset..
16360 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 34 7d 20 54  **.** {H17374} T
16370 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
16380 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
16390 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
163a0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
163b0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
163c0 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
163d0 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
163e0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 64 64 65  **          adde
163f0 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
16400 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
16410 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
16420 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20  lloc()],.**     
16430 20 20 20 20 20 62 75 74 20 6e 6f 74 20 6f 76 65       but not ove
16440 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
16450 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
16460 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
16470 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75  .**          rou
16480 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69  tines that [sqli
16490 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61  te3_malloc()] ma
164a0 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  y call..**.** {H
164b0 31 37 33 37 35 7d 20 54 68 65 20 6d 65 6d 6f 72  17375} The memor
164c0 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
164d0 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
164e0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
164f0 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  of.**          [
16500 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
16510 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
16520 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
16530 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20  ter to.**       
16540 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f     [sqlite3_memo
16550 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
16560 69 73 20 74 72 75 65 2e 20 20 54 68 65 20 76 61  is true.  The va
16570 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
16580 20 20 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c           by [sql
16590 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
165a0 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
165b0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
165c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 69  .**          pri
165d0 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
165e0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
165f0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
16600 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c  _used(void);.sql
16610 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
16620 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
16630 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
16640 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
16650 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
16660 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
16670 74 6f 72 20 7b 48 31 37 33 39 30 7d 20 3c 53 32  tor {H17390} <S2
16680 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  0000>.**.** SQLi
16690 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
166a0 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
166b0 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
166c0 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
166d0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
166e0 63 74 20 72 61 6e 64 6f 6d 20 52 4f 57 49 44 73  ct random ROWIDs
166f0 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
16700 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
16710 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
16720 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
16730 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
16740 6c 65 20 52 4f 57 49 44 2e 20 20 54 68 65 20 50  le ROWID.  The P
16750 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
16760 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
16770 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
16780 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
16790 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
167a0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
167b0 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
167c0 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
167d0 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
167e0 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
167f0 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
16800 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74   this routine st
16810 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20  ores N bytes of 
16820 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
16830 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20  buffer P..**.** 
16840 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
16850 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69  his routine is i
16860 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69  nvoked (either i
16870 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a  nternally or by.
16880 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
16890 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20  on) the PRNG is 
168a0 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
168b0 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
168c0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61  .** from the xRa
168d0 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
168e0 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
168f0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
16900 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73  ect..** On all s
16910 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
16920 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64  tions, the pseud
16930 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
16940 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
16950 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
16960 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
16970 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
16980 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
16990 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 49   method..**.** I
169a0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
169b0 20 7b 48 31 37 33 39 32 7d 20 54 68 65 20 5b 73   {H17392} The [s
169c0 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
169d0 73 28 4e 2c 50 29 5d 20 69 6e 74 65 72 66 61 63  s(N,P)] interfac
169e0 65 20 77 72 69 74 65 73 20 4e 20 62 79 74 65 73  e writes N bytes
169f0 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
16a00 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
16a10 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
16a20 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2f  nto buffer P..*/
16a30 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61  .void sqlite3_ra
16a40 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
16a50 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
16a60 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
16a70 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
16a80 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20  ation Callbacks 
16a90 7b 48 31 32 35 30 30 7d 20 3c 53 37 30 31 30 30  {H12500} <S70100
16aa0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  >.**.** This rou
16ab0 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
16ac0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
16ad0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
16ae0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
16af0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
16b00 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
16b10 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
16b20 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
16b30 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
16b40 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
16b50 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
16b60 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
16b70 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
16b80 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
16b90 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
16ba0 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
16bb0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
16bc0 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  e16()] and [sqli
16bd0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
16be0 28 29 5d 2e 20 20 41 74 20 76 61 72 69 6f 75 73  ()].  At various
16bf0 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e  .** points durin
16c00 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f  g the compilatio
16c10 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f  n process, as lo
16c20 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65  gic is being cre
16c30 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f  ated.** to perfo
16c40 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f  rm various actio
16c50 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ns, the authoriz
16c60 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
16c70 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65  nvoked to.** see
16c80 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e   if those action
16c90 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20  s are allowed.  
16ca0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
16cb0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
16cc0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
16cd0 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
16ce0 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
16cf0 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
16d00 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
16d10 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
16d20 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
16d30 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
16d40 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
16d50 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
16d60 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
16d70 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
16d80 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
16d90 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
16da0 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 49 66 20  h an error.  If 
16db0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
16dc0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
16dd0 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
16de0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
16df0 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
16e00 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
16e10 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74  _DENY].** then t
16e20 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
16e30 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
16e40 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
16e50 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74  t triggered.** t
16e60 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  he authorizer wi
16e70 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
16e80 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
16e90 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
16ea0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
16eb0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74  SQLITE_OK], that
16ec0 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61   means the opera
16ed0 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65  tion.** requeste
16ee0 64 20 69 73 20 6f 6b 2e 20 20 57 68 65 6e 20 74  d is ok.  When t
16ef0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
16f00 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
16f10 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
16f20 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
16f30 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
16f40 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
16f50 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
16f60 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
16f70 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
16f80 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
16f90 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
16fa0 73 20 64 65 6e 69 65 64 2e 20 20 49 66 20 74 68  s denied.  If th
16fb0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 64  e authorizer cod
16fc0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
16fd0 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
16fe0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
16ff0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
17000 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
17010 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
17020 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
17030 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
17040 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
17050 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
17060 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
17070 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
17080 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
17090 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
170a0 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
170b0 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
170c0 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
170d0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
170e0 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
170f0 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
17100 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
17110 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
17120 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  le..**.** The fi
17130 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
17140 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
17150 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
17160 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a  py of the third.
17170 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
17180 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
17190 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
171a0 65 72 66 61 63 65 2e 20 54 68 65 20 73 65 63 6f  erface. The seco
171b0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
171c0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
171d0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53  is an integer [S
171e0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
171f0 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
17200 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
17210 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
17220 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
17230 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 74 68  ed. The third th
17240 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
17250 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
17260 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65   callback are ze
17270 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
17280 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
17290 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  in additional.**
172a0 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
172b0 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
172c0 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
172d0 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
172e0 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71  is used when [sq
172f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
17300 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51  preparing].** SQ
17310 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
17320 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  m an untrusted s
17330 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
17340 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
17350 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e  atements.** do n
17360 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
17370 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e   data they are n
17380 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
17390 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
173a0 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f  do not.** try to
173b0 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
173c0 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
173d0 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
173e0 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
173f0 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
17400 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
17410 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
17420 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
17430 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
17440 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
17450 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
17460 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
17470 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
17480 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
17490 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
174a0 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
174b0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
174c0 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
174d0 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
174e0 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
174f0 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
17500 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
17510 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
17520 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
17530 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
17540 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
17550 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
17560 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
17570 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
17580 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
17590 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
175a0 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
175b0 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
175c0 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
175d0 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
175e0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
175f0 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
17600 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
17610 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
17620 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
17630 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
17640 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
17650 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
17660 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  * Only a single 
17670 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
17680 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
17690 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
176a0 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
176b0 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
176c0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
176d0 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
176e0 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
176f0 20 63 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20   call.  Disable 
17700 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
17710 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
17720 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
17730 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
17740 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
17750 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  efault..**.** No
17760 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
17770 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
17780 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
17790 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  during.** [sqlit
177a0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
177b0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20   its variants.  
177c0 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73  Authorization is
177d0 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65   not.** performe
177e0 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65  d during stateme
177f0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e  nt evaluation in
17800 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
17810 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
17820 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  NTS:.**.** {H125
17830 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  01} The [sqlite3
17840 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
17850 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63  D,...)] interfac
17860 65 20 72 65 67 69 73 74 65 72 73 20 61 0a 2a 2a  e registers a.**
17870 20 20 20 20 20 20 20 20 20 20 61 75 74 68 6f 72            author
17880 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
17890 74 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  th database conn
178a0 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20  ection D..**.** 
178b0 7b 48 31 32 35 30 32 7d 20 54 68 65 20 61 75 74  {H12502} The aut
178c0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
178d0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
178e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
178f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65  e.**          be
17900 69 6e 67 20 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  ing compiled..**
17910 0a 2a 2a 20 7b 48 31 32 35 30 33 7d 20 49 66 20  .** {H12503} If 
17920 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
17930 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
17940 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
17950 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  than.**         
17960 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
17970 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
17980 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  r [SQLITE_DENY],
17990 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
179a0 20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70    the [sqlite3_p
179b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
179c0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
179d0 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 20  that caused.**  
179e0 20 20 20 20 20 20 20 20 74 68 65 20 61 75 74 68          the auth
179f0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
17a00 74 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69  to run shall fai
17a10 6c 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20  l with an.**    
17a20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52        [SQLITE_ER
17a30 52 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20  ROR] error code 
17a40 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61  and an appropria
17a50 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  te error message
17a60 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 34 7d  ..**.** {H12504}
17a70 20 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72   When the author
17a80 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
17a90 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
17aa0 5d 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ], the operation
17ab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 73  .**          des
17ac0 63 72 69 62 65 64 20 69 73 20 70 72 6f 63 65 73  cribed is proces
17ad0 73 65 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a  sed normally..**
17ae0 0a 2a 2a 20 7b 48 31 32 35 30 35 7d 20 57 68 65  .** {H12505} Whe
17af0 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  n the authorizer
17b00 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
17b10 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
17b20 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
17b30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
17b40 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
17b50 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
17b60 63 61 75 73 65 64 20 74 68 65 0a 2a 2a 20 20 20  caused the.**   
17b70 20 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65         authorize
17b80 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75  r callback to ru
17b90 6e 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20  n shall fail.** 
17ba0 20 20 20 20 20 20 20 20 20 77 69 74 68 20 61 6e           with an
17bb0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
17bc0 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61  error code and a
17bd0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a  n error message.
17be0 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 70 6c  **          expl
17bf0 61 69 6e 69 6e 67 20 74 68 61 74 20 61 63 63 65  aining that acce
17c00 73 73 20 69 73 20 64 65 6e 69 65 64 2e 0a 2a 2a  ss is denied..**
17c10 0a 2a 2a 20 7b 48 31 32 35 30 36 7d 20 49 66 20  .** {H12506} If 
17c20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
17c30 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72  ode (the 2nd par
17c40 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
17c50 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20  thorizer.**     
17c60 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69       callback) i
17c70 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20  s [SQLITE_READ] 
17c80 61 6e 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  and the authoriz
17c90 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
17ca0 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
17cb0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
17cc0 20 74 68 65 6e 20 74 68 65 20 70 72 65 70 61 72   then the prepar
17cd0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
17ce0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 0a 2a  constructed to.*
17cf0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 65 72  *          inser
17d00 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  t a NULL value i
17d10 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
17d20 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
17d30 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 20   would have.**  
17d40 20 20 20 20 20 20 20 20 62 65 65 6e 20 72 65 61          been rea
17d50 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
17d60 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
17d70 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30  ed..**.** {H1250
17d80 37 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  7} If the author
17d90 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32  izer code (the 2
17da0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
17db0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a  the authorizer.*
17dc0 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
17dd0 61 63 6b 29 20 69 73 20 61 6e 79 74 68 69 6e 67  ack) is anything
17de0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
17df0 49 54 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e 0a  ITE_READ], then.
17e00 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65  **          a re
17e10 74 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  turn of [SQLITE_
17e20 49 47 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 20  IGNORE] has the 
17e30 73 61 6d 65 20 65 66 66 65 63 74 20 61 73 20 5b  same effect as [
17e40 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2e 0a 2a 2a  SQLITE_DENY]..**
17e50 0a 2a 2a 20 7b 48 31 32 35 31 30 7d 20 54 68 65  .** {H12510} The
17e60 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
17e70 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
17e80 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
17e90 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20   copy of.**     
17ea0 20 20 20 20 20 74 68 65 20 74 68 69 72 64 20 70       the third p
17eb0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
17ec0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
17ed0 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
17ee0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  face..**.** {H12
17ef0 35 31 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20  511} The second 
17f00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
17f10 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
17f20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20  integer.**      
17f30 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59      [SQLITE_COPY
17f40 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
17f50 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
17f60 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
17f70 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
17f80 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
17f90 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 32  d..**.** {H12512
17fa0 7d 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f  } The third thro
17fb0 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
17fc0 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ters to the call
17fd0 62 61 63 6b 20 61 72 65 0a 2a 2a 20 20 20 20 20  back are.**     
17fe0 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
17ff0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
18000 74 20 63 6f 6e 74 61 69 6e 0a 2a 2a 20 20 20 20  t contain.**    
18010 20 20 20 20 20 20 61 64 64 69 74 69 6f 6e 61 6c        additional
18020 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
18030 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
18040 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
18050 2a 20 7b 48 31 32 35 32 30 7d 20 45 61 63 68 20  * {H12520} Each 
18060 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
18070 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
18080 29 5d 20 6f 76 65 72 72 69 64 65 73 0a 2a 2a 20  )] overrides.** 
18090 20 20 20 20 20 20 20 20 20 61 6e 79 20 70 72 65           any pre
180a0 76 69 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c 65  viously installe
180b0 64 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  d authorizer..**
180c0 0a 2a 2a 20 7b 48 31 32 35 32 31 7d 20 41 20 4e  .** {H12521} A N
180d0 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d  ULL authorizer m
180e0 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74  eans that no aut
180f0 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20  horization.**   
18100 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20         callback 
18110 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
18120 2a 20 7b 48 31 32 35 32 32 7d 20 54 68 65 20 64  * {H12522} The d
18130 65 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65  efault authorize
18140 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  r is NULL..*/.in
18150 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
18160 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
18170 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
18180 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
18190 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
181a0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
181b0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
181c0 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
181d0 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
181e0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
181f0 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b  r Return Codes {
18200 48 31 32 35 39 30 7d 20 3c 48 31 32 35 30 30 3e  H12590} <H12500>
18210 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
18220 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
18230 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
18240 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
18250 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
18260 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
18270 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
18280 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
18290 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
182a0 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
182b0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
182c0 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
182d0 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
182e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
182f0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
18300 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
18310 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
18320 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
18330 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e  ation..*/.#defin
18340 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
18350 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
18360 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
18370 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
18380 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
18390 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
183a0 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
183b0 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
183c0 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
183d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
183e0 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
183f0 6f 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 35 30  on Codes {H12550
18400 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a  } <H12500>.**.**
18410 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
18420 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
18430 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
18440 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
18450 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
18460 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
18470 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
18480 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
18490 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
184a0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
184b0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
184c0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
184d0 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
184e0 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
184f0 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
18500 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
18510 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
18520 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
18530 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
18540 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
18550 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
18560 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
18570 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
18580 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
18590 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
185a0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
185b0 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
185c0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
185d0 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
185e0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
185f0 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
18600 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
18610 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
18620 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
18630 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
18640 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
18650 65 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70  eter.  The 5th p
18660 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
18670 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
18680 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
18690 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
186a0 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
186b0 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  p",.** etc.) if 
186c0 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65  applicable.  The
186d0 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
186e0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
186f0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
18700 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
18710 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
18720 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
18730 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
18740 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
18750 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
18760 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
18770 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
18780 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
18790 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
187a0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
187b0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 31 7d  :.**.** {H12551}
187c0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
187d0 6d 65 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 20  meter to an.**  
187e0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
187f0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
18800 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
18810 6c 62 61 63 6b 5d 20 69 73 20 61 6c 77 61 79 73  lback] is always
18820 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20   an integer.**  
18830 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
18840 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65  COPY | authorize
18850 72 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  r code] that spe
18860 63 69 66 69 65 73 20 77 68 61 74 20 61 63 74 69  cifies what acti
18870 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  on.**          i
18880 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
18890 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35  ed..**.** {H1255
188a0 32 7d 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  2} The 3rd and 4
188b0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
188c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
188d0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
188e0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
188f0 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63  rization callbac
18900 6b 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  k].**          w
18910 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
18920 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
18930 69 6e 67 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20  ing on which.** 
18940 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
18950 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a  _COPY | authoriz
18960 65 72 20 63 6f 64 65 5d 20 69 73 20 75 73 65 64  er code] is used
18970 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
18980 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
18990 7b 48 31 32 35 35 33 7d 20 54 68 65 20 35 74 68  {H12553} The 5th
189a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
189b0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
189c0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
189d0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
189e0 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 69 73 20  er callback] is 
189f0 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 20 20 20 20  the name.**     
18a00 20 20 20 20 20 6f 66 20 74 68 65 20 64 61 74 61       of the data
18a10 62 61 73 65 20 28 65 78 61 6d 70 6c 65 3a 20 22  base (example: "
18a20 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 65  main", "temp", e
18a30 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
18a40 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35  le..**.** {H1255
18a50 34 7d 20 54 68 65 20 36 74 68 20 70 61 72 61 6d  4} The 6th param
18a60 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 20  eter to the.**  
18a70 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
18a80 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
18a90 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
18aa0 6c 62 61 63 6b 5d 20 69 73 20 74 68 65 20 6e 61  lback] is the na
18ab0 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  me.**          o
18ac0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
18ad0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
18ae0 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
18af0 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  ible for.**     
18b00 20 20 20 20 20 74 68 65 20 61 63 63 65 73 73 20       the access 
18b10 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
18b20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
18b30 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
18b40 6c 79 20 66 72 6f 6d 0a 2a 2a 20 20 20 20 20 20  ly from.**      
18b50 20 20 20 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51      top-level SQ
18b60 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
18b70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18b80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18b90 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
18ba0 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
18bb0 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
18bc0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
18bd0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
18be0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
18bf0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
18c00 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18c10 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
18c20 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
18c30 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
18c40 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18c50 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18c60 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
18c70 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
18c80 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
18c90 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
18ca0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18cb0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
18cc0 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
18cd0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
18ce0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
18cf0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18d00 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
18d10 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
18d20 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
18d30 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
18d40 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18d50 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
18d60 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
18d70 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
18d80 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18d90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18da0 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
18db0 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
18dc0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
18dd0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18de0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18df0 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
18e00 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
18e10 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
18e20 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18e30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18e40 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
18e50 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
18e60 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
18e70 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18e80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18e90 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
18ea0 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
18eb0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
18ec0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
18ed0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18ee0 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
18ef0 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
18f00 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
18f10 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
18f20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
18f30 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
18f40 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
18f50 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
18f60 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
18f70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
18f80 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
18f90 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
18fa0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
18fb0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
18fc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
18fd0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
18fe0 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
18ff0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
19000 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
19010 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
19020 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
19030 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
19040 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
19050 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19060 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
19070 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
19080 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
19090 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
190a0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
190b0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
190c0 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
190d0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
190e0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
190f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19100 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
19110 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
19120 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
19130 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
19140 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19150 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
19160 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
19170 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
19180 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
19190 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
191a0 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
191b0 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
191c0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
191d0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
191e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
191f0 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
19200 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
19210 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
19220 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
19230 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19240 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
19250 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
19260 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19270 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19280 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19290 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
192a0 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
192b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
192c0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
192d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
192e0 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
192f0 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
19300 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
19310 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
19320 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19330 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
19340 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
19350 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
19360 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
19370 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19380 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
19390 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
193a0 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
193b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
193c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
193d0 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
193e0 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
193f0 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
19400 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
19410 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
19420 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
19430 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
19440 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
19450 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
19460 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
19470 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
19480 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
19490 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
194a0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
194b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
194c0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
194d0 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
194e0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
194f0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
19500 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
19510 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
19520 33 31 20 20 20 2f 2a 20 46 75 6e 63 74 69 6f 6e  31   /* Function
19530 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
19540 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19550 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
19560 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
19570 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
19580 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   used */../*.** 
19590 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
195a0 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
195b0 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 32 32 38  Functions {H1228
195c0 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 20 45  0} <S60400>.** E
195d0 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a  XPERIMENTAL.**.*
195e0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
195f0 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
19600 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
19610 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
19620 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
19630 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
19640 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
19650 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
19660 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
19670 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
19680 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
19690 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
196a0 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
196b0 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
196c0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
196d0 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
196e0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
196f0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  The callback ret
19700 75 72 6e 73 20 61 20 55 54 46 2d 38 20 72 65 6e  urns a UTF-8 ren
19710 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 53 51  dering of the SQ
19720 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
19730 0a 2a 2a 20 61 73 20 74 68 65 20 73 74 61 74 65  .** as the state
19740 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
19750 73 20 65 78 65 63 75 74 69 6e 67 2e 20 20 41 64  s executing.  Ad
19760 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63  ditional callbac
19770 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ks occur.** as e
19780 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
19790 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
197a0 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
197b0 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
197c0 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
197d0 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
197e0 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
197f0 74 68 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a  the trigger..**.
19800 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
19810 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
19820 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
19830 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f  rofile() is invo
19840 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53  ked.** as each S
19850 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
19860 69 73 68 65 73 2e 20 20 54 68 65 20 70 72 6f 66  ishes.  The prof
19870 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
19880 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
19890 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
198a0 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
198b0 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
198c0 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
198d0 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
198e0 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
198f0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  n..**.** INVARIA
19900 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  NTS:.**.** {H122
19910 38 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  81} The callback
19920 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
19930 65 72 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ered by [sqlite3
19940 5f 74 72 61 63 65 28 29 5d 20 69 73 0a 2a 2a 20  _trace()] is.** 
19950 20 20 20 20 20 20 20 20 20 77 68 65 6e 65 76 65           wheneve
19960 72 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  r an SQL stateme
19970 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
19980 74 6f 20 65 78 65 63 75 74 65 20 61 6e 64 0a 2a  to execute and.*
19990 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e 65  *          whene
199a0 76 65 72 20 61 20 74 72 69 67 67 65 72 20 73 75  ver a trigger su
199b0 62 70 72 6f 67 72 61 6d 20 66 69 72 73 74 20 62  bprogram first b
199c0 65 67 69 6e 73 20 74 6f 20 72 75 6e 2e 0a 2a 2a  egins to run..**
199d0 0a 2a 2a 20 7b 48 31 32 32 38 32 7d 20 45 61 63  .** {H12282} Eac
199e0 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  h call to [sqlit
199f0 65 33 5f 74 72 61 63 65 28 29 5d 20 6f 76 65 72  e3_trace()] over
19a00 72 69 64 65 73 20 74 68 65 20 70 72 65 76 69 6f  rides the previo
19a10 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  usly.**         
19a20 20 72 65 67 69 73 74 65 72 65 64 20 74 72 61 63   registered trac
19a30 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  e callback..**.*
19a40 2a 20 7b 48 31 32 32 38 33 7d 20 41 20 4e 55 4c  * {H12283} A NUL
19a50 4c 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  L trace callback
19a60 20 64 69 73 61 62 6c 65 73 20 74 72 61 63 69 6e   disables tracin
19a70 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 34  g..**.** {H12284
19a80 7d 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  } The first argu
19a90 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63  ment to the trac
19aa0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  e callback is a 
19ab0 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20  copy of.**      
19ac0 20 20 20 20 74 68 65 20 70 6f 69 6e 74 65 72 20      the pointer 
19ad0 77 68 69 63 68 20 77 61 73 20 74 68 65 20 33 72  which was the 3r
19ae0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  d argument to [s
19af0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 2e  qlite3_trace()].
19b00 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 35 7d 20  .**.** {H12285} 
19b10 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
19b20 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65  ent to the trace
19b30 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a   callback is a.*
19b40 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
19b50 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
19b60 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
19b70 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ng the original 
19b80 74 65 78 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  text.**         
19b90 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   of the SQL stat
19ba0 65 6d 65 6e 74 20 61 73 20 69 74 20 77 61 73 20  ement as it was 
19bb0 70 61 73 73 65 64 20 69 6e 74 6f 20 5b 73 71 6c  passed into [sql
19bc0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
19bd0 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  )].**          o
19be0 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
19bf0 2c 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d  , or an SQL comm
19c00 65 6e 74 20 69 6e 64 69 63 61 74 69 6e 67 20 74  ent indicating t
19c10 68 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  he beginning.** 
19c20 20 20 20 20 20 20 20 20 20 6f 66 20 61 20 74 72           of a tr
19c30 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d  igger subprogram
19c40 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 37 7d  ..**.** {H12287}
19c50 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   The callback fu
19c60 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
19c70 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  d by [sqlite3_pr
19c80 6f 66 69 6c 65 28 29 5d 20 69 73 20 69 6e 76 6f  ofile()] is invo
19c90 6b 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ked.**          
19ca0 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
19cb0 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a  ement finishes..
19cc0 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 38 7d 20 54  **.** {H12288} T
19cd0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
19ce0 65 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c  er to the profil
19cf0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  e callback is a 
19d00 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20  copy of.**      
19d10 20 20 20 20 74 68 65 20 33 72 64 20 70 61 72 61      the 3rd para
19d20 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
19d30 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2e 0a 2a 2a  3_profile()]..**
19d40 0a 2a 2a 20 7b 48 31 32 32 38 39 7d 20 54 68 65  .** {H12289} The
19d50 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
19d60 72 20 74 6f 20 74 68 65 20 70 72 6f 66 69 6c 65  r to the profile
19d70 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 0a 2a   callback is a.*
19d80 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 2d  *          zero-
19d90 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
19da0 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 6f 6e   string that con
19db0 74 61 69 6e 73 20 74 68 65 20 63 6f 6d 70 6c 65  tains the comple
19dc0 74 65 20 74 65 78 74 20 6f 66 0a 2a 2a 20 20 20  te text of.**   
19dd0 20 20 20 20 20 20 20 74 68 65 20 53 51 4c 20 73         the SQL s
19de0 74 61 74 65 6d 65 6e 74 20 61 73 20 69 74 20 77  tatement as it w
19df0 61 73 20 70 72 6f 63 65 73 73 65 64 20 62 79 20  as processed by 
19e00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
19e10 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20  _v2()].**       
19e20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69 76 61     or the equiva
19e30 6c 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  lent..**.** {H12
19e40 32 39 30 7d 20 54 68 65 20 74 68 69 72 64 20 70  290} The third p
19e50 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
19e60 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
19e70 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 0a   is an estimate.
19e80 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  **          of t
19e90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e  he number of nan
19ea0 6f 73 65 63 6f 6e 64 73 20 6f 66 20 77 61 6c 6c  oseconds of wall
19eb0 2d 63 6c 6f 63 6b 20 74 69 6d 65 20 72 65 71 75  -clock time requ
19ec0 69 72 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 20  ired to.**      
19ed0 20 20 20 20 72 75 6e 20 74 68 65 20 53 51 4c 20      run the SQL 
19ee0 73 74 61 74 65 6d 65 6e 74 20 66 72 6f 6d 20 73  statement from s
19ef0 74 61 72 74 20 74 6f 20 66 69 6e 69 73 68 2e 0a  tart to finish..
19f00 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
19f10 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
19f20 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
19f30 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
19f40 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20  ), void*);.void 
19f50 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
19f60 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
19f70 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
19f80 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
19f90 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
19fa0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
19fb0 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
19fc0 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
19fd0 6b 73 20 7b 48 31 32 39 31 30 7d 20 3c 53 36 30  ks {H12910} <S60
19fe0 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  400>.**.** This 
19ff0 72 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72  routine configur
1a000 65 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  es a callback fu
1a010 6e 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20  nction - the.** 
1a020 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
1a030 6b 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f  k - that is invo
1a040 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
1a050 20 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20   during long.** 
1a060 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
1a070 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1a080 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
1a090 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
1a0a0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1a0b0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
1a0c0 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
1a0d0 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
1a0e0 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
1a0f0 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
1a100 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  query..**.** If 
1a110 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
1a120 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
1a130 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
1a140 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
1a150 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
1a160 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
1a170 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
1a180 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
1a190 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 64 69  tton on a GUI di
1a1a0 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
1a1b0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
1a1c0 2a 20 7b 48 31 32 39 31 31 7d 20 54 68 65 20 63  * {H12911} The c
1a1d0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1a1e0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
1a1f0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1a200 68 61 6e 64 6c 65 72 28 29 0a 2a 2a 20 20 20 20  handler().**    
1a210 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65 64        is invoked
1a220 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
1a230 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
1a240 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20  g calls to.**   
1a250 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1a260 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  step()]..**.** {
1a270 48 31 32 39 31 32 7d 20 54 68 65 20 70 72 6f 67  H12912} The prog
1a280 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73  ress callback is
1a290 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f   invoked once fo
1a2a0 72 20 65 76 65 72 79 20 4e 20 76 69 72 74 75 61  r every N virtua
1a2b0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 61  l.**          ma
1a2c0 63 68 69 6e 65 20 6f 70 63 6f 64 65 73 2c 20 77  chine opcodes, w
1a2d0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
1a2e0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
1a2f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1a300 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65   [sqlite3_progre
1a310 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d 20 63 61  ss_handler()] ca
1a320 6c 6c 20 74 68 61 74 20 72 65 67 69 73 74 65 72  ll that register
1a330 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ed.**          t
1a340 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 49 66  he callback.  If
1a350 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
1a360 31 2c 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  1, sqlite3_progr
1a370 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 0a 2a 2a  ess_handler().**
1a380 20 20 20 20 20 20 20 20 20 20 61 63 74 73 20 61            acts a
1a390 73 20 69 66 20 61 20 4e 55 4c 4c 20 70 72 6f 67  s if a NULL prog
1a3a0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 68 61 64  ress handler had
1a3b0 20 62 65 65 6e 20 73 70 65 63 69 66 69 65 64 2e   been specified.
1a3c0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 33 7d 20  .**.** {H12913} 
1a3d0 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  The progress cal
1a3e0 6c 62 61 63 6b 20 69 74 73 65 6c 66 20 69 73 20  lback itself is 
1a3f0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
1a400 65 20 74 68 69 72 64 0a 2a 2a 20 20 20 20 20 20  e third.**      
1a410 20 20 20 20 61 72 67 75 6d 65 6e 74 20 74 6f 20      argument to 
1a420 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
1a430 5f 68 61 6e 64 6c 65 72 28 29 2e 0a 2a 2a 0a 2a  _handler()..**.*
1a440 2a 20 7b 48 31 32 39 31 34 7d 20 54 68 65 20 66  * {H12914} The f
1a450 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
1a460 6f 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  o sqlite3_progre
1a470 73 73 5f 68 61 6e 64 6c 65 72 28 29 20 69 73 20  ss_handler() is 
1a480 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 6f  a.**          vo
1a490 69 64 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  id pointer passe
1a4a0 64 20 74 6f 20 74 68 65 20 70 72 6f 67 72 65 73  d to the progres
1a4b0 73 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  s callback.**   
1a4c0 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20         function 
1a4d0 65 61 63 68 20 74 69 6d 65 20 69 74 20 69 73 20  each time it is 
1a4e0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  invoked..**.** {
1a4f0 48 31 32 39 31 35 7d 20 49 66 20 61 20 63 61 6c  H12915} If a cal
1a500 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
1a510 65 70 28 29 5d 20 72 65 73 75 6c 74 73 20 69 6e  ep()] results in
1a520 20 66 65 77 65 72 20 74 68 61 6e 20 4e 20 6f 70   fewer than N op
1a530 63 6f 64 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  codes.**        
1a540 20 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64    being executed
1a550 2c 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72  , then the progr
1a560 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ess callback is 
1a570 6e 65 76 65 72 20 69 6e 76 6f 6b 65 64 2e 0a 2a  never invoked..*
1a580 2a 0a 2a 2a 20 7b 48 31 32 39 31 36 7d 20 45 76  *.** {H12916} Ev
1a590 65 72 79 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ery call to [sql
1a5a0 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1a5b0 6e 64 6c 65 72 28 29 5d 0a 2a 2a 20 20 20 20 20  ndler()].**     
1a5c0 20 20 20 20 20 6f 76 65 72 77 72 69 74 65 73 20       overwrites 
1a5d0 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 72  any previously r
1a5e0 65 67 69 73 74 65 72 65 64 20 70 72 6f 67 72 65  egistered progre
1a5f0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  ss handler..**.*
1a600 2a 20 7b 48 31 32 39 31 37 7d 20 49 66 20 74 68  * {H12917} If th
1a610 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1a620 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  er callback is N
1a630 55 4c 4c 20 74 68 65 6e 20 6e 6f 20 70 72 6f 67  ULL then no prog
1a640 72 65 73 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  ress.**         
1a650 20 68 61 6e 64 6c 65 72 20 69 73 20 69 6e 76 6f   handler is invo
1a660 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ked..**.** {H129
1a670 31 38 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72  18} If the progr
1a680 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
1a690 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 6f 74  urns a result ot
1a6a0 68 65 72 20 74 68 61 6e 20 30 2c 20 74 68 65 6e  her than 0, then
1a6b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1a6c0 20 62 65 68 61 76 69 6f 72 20 69 73 20 61 20 69   behavior is a i
1a6d0 66 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  f [sqlite3_inter
1a6e0 72 75 70 74 28 29 5d 20 68 61 64 20 62 65 65 6e  rupt()] had been
1a6f0 20 63 61 6c 6c 65 64 2e 0a 2a 2a 20 20 20 20 20   called..**     
1a700 20 20 20 20 20 3c 53 33 30 35 30 30 3e 0a 2a 2f       <S30500>.*/
1a710 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72  .void sqlite3_pr
1a720 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73  ogress_handler(s
1a730 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e  qlite3*, int, in
1a740 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69  t(*)(void*), voi
1a750 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1a760 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20  3REF: Opening A 
1a770 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e  New Database Con
1a780 6e 65 63 74 69 6f 6e 20 7b 48 31 32 37 30 30 7d  nection {H12700}
1a790 20 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S40200>.**.** 
1a7a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
1a7b0 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
1a7c0 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73  tabase file whos
1a7d0 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20  e name is given 
1a7e0 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  by the.** filena
1a7f0 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65  me argument. The
1a800 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1a810 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
1a820 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a  d as UTF-8 for.*
1a830 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1a840 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1a850 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54  n_v2() and as UT
1a860 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
1a870 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72  ve byte.** order
1a880 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
1a890 6e 31 36 28 29 2e 20 41 20 5b 64 61 74 61 62 61  n16(). A [databa
1a8a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
1a8b0 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
1a8c0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
1a8d0 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
1a8e0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
1a8f0 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
1a900 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
1a910 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
1a920 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
1a930 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1a940 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
1a950 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
1a960 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
1a970 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
1a980 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
1a990 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
1a9a0 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65  * object. If the
1a9b0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1a9c0 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
1a9d0 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
1a9e0 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
1a9f0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
1aa00 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
1aa10 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
1aa20 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
1aa30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
1aa40 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
1aa50 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
1aa60 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
1aa70 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
1aa80 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
1aa90 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
1aaa0 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a   of the error..*
1aab0 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
1aac0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68   encoding for th
1aad0 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
1aae0 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73  be UTF-8 if.** s
1aaf0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
1ab00 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1ab10 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64  () is called and
1ab20 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68  .** UTF-16 in th
1ab30 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
1ab40 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f  der if sqlite3_o
1ab50 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e  pen16() is used.
1ab60 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
1ab70 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
1ab80 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
1ab90 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
1aba0 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
1abb0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
1abc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1abd0 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
1abe0 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
1abf0 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
1ac00 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
1ac10 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
1ac20 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
1ac30 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1ac40 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
1ac50 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
1ac60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
1ac70 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
1ac80 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
1ac90 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
1aca0 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
1acb0 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
1acc0 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
1acd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
1ace0 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
1acf0 74 65 72 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  ter can take one
1ad00 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
1ad10 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
1ad20 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
1ad30 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
1ad40 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1ad50 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 3a 0a  _NOMUTEX] flag:.
1ad60 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
1ad70 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1ad80 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
1ad90 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
1ada0 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
1adb0 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
1adc0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1add0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
1ade0 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
1adf0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
1ae00 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1ae10 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1ae20 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
1ae30 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
1ae40 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1ae50 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
1ae60 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
1ae70 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
1ae80 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
1ae90 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
1aea0 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
1aeb0 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
1aec0 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
1aed0 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
1aee0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
1aef0 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
1af00 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
1af10 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53  dd>.**.** <dt>[S
1af20 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1af30 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
1af40 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
1af50 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1af60 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1af70 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
1af80 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
1af90 63 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a  creates it if.**
1afa0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
1afb0 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
1afc0 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
1afd0 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
1afe0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
1aff0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
1b000 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
1b010 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  </dd>.** </dl>.*
1b020 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
1b030 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1b040 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1b050 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
1b060 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
1b070 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20   shown above or 
1b080 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69  one of the combi
1b090 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
1b0a0 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20  ove combined.** 
1b0b0 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
1b0c0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
1b0d0 6c 61 67 2c 20 74 68 65 6e 20 74 68 65 20 62 65  lag, then the be
1b0e0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
1b0f0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ned..**.** If th
1b100 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  e [SQLITE_OPEN_N
1b110 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  OMUTEX] flag is 
1b120 73 65 74 2c 20 74 68 65 6e 20 6d 75 74 65 78 65  set, then mutexe
1b130 73 20 6f 6e 20 74 68 65 0a 2a 2a 20 6f 70 65 6e  s on the.** open
1b140 65 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ed [database con
1b150 6e 65 63 74 69 6f 6e 5d 20 61 72 65 20 64 69 73  nection] are dis
1b160 61 62 6c 65 64 20 61 6e 64 20 74 68 65 20 61 70  abled and the ap
1b170 70 6c 69 61 74 69 6f 6e 20 6d 75 73 74 0a 2a 2a  pliation must.**
1b180 20 69 6e 73 75 72 65 20 74 68 61 74 20 61 63 63   insure that acc
1b190 65 73 73 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ess to the [data
1b1a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1b1b0 20 61 6e 64 20 69 74 73 20 61 73 73 6f 63 69 61   and its associa
1b1c0 74 65 64 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  ted.** [prepared
1b1d0 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 69 73 20   statements] is 
1b1e0 73 65 72 69 61 6c 69 7a 65 64 2e 20 20 54 68 65  serialized.  The
1b1f0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1b200 4d 55 54 45 58 5d 20 66 6c 61 67 0a 2a 2a 20 69  MUTEX] flag.** i
1b210 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 62 65  s the default be
1b220 68 61 76 69 6f 72 20 69 73 20 53 51 4c 69 74 65  havior is SQLite
1b230 20 69 73 20 63 6f 6e 66 69 67 75 72 65 64 20 75   is configured u
1b240 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  sing the.** [SQL
1b250 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
1b260 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
1b270 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
1b280 54 48 52 45 41 44 5d 20 6f 70 74 69 6f 6e 73 0a  THREAD] options.
1b290 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
1b2a0 6f 6e 66 69 67 28 29 5d 2e 20 20 54 68 65 20 5b  onfig()].  The [
1b2b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1b2c0 54 45 58 5d 20 66 6c 61 67 20 6f 6e 6c 79 20 6d  TEX] flag only m
1b2d0 61 6b 65 73 20 61 0a 2a 2a 20 64 69 66 66 65 72  akes a.** differ
1b2e0 65 6e 63 65 20 77 68 65 6e 20 53 51 4c 69 74 65  ence when SQLite
1b2f0 20 69 73 20 69 6e 20 69 74 73 20 64 65 66 61 75   is in its defau
1b300 6c 74 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  lt [SQLITE_CONFI
1b310 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 20 6d 6f  G_SERIALIZED] mo
1b320 64 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  de..**.** If the
1b330 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
1b340 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
1b350 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
1b360 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
1b370 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
1b380 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
1b390 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 6e  ection.  This in
1b3a0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
1b3b0 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65   will vanish whe
1b3c0 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
1b3d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1b3e0 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20  closed.  Future 
1b3f0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1b400 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65  te might.** make
1b410 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e   use of addition
1b420 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e  al special filen
1b430 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20  ames that begin 
1b440 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61  with the ":" cha
1b450 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73  racter..** It is
1b460 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
1b470 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  t when a databas
1b480 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61  e filename actua
1b490 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77  lly does begin w
1b4a0 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61  ith.** a ":" cha
1b4b0 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c  racter you shoul
1b4c0 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c  d prefix the fil
1b4d0 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74  ename with a pat
1b4e0 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a  hname such as.**
1b4f0 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61   "./" to avoid a
1b500 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  mbiguity..**.** 
1b510 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1b520 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
1b530 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
1b540 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  te, temporary.**
1b550 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73   on-disk databas
1b560 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
1b570 64 2e 20 20 54 68 69 73 20 70 72 69 76 61 74 65  d.  This private
1b580 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1b590 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
1b5a0 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
1b5b0 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
1b5c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
1b5d0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   closed..**.** T
1b5e0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1b5f0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
1b600 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
1b610 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
1b620 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1b630 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
1b640 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1b650 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
1b660 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
1b670 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b680 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
1b690 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
1b6a0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
1b6b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1b6c0 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
1b6d0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1b6e0 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
1b6f0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
1b700 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
1b710 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
1b720 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
1b730 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
1b740 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
1b750 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
1b760 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
1b770 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
1b780 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
1b790 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
1b7a0 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
1b7b0 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
1b7c0 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
1b7d0 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
1b7e0 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
1b7f0 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
1b800 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
1b810 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1b820 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
1b830 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  _v2()..**.** INV
1b840 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
1b850 48 31 32 37 30 31 7d 20 54 68 65 20 5b 73 71 6c  H12701} The [sql
1b860 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1b870 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1b880 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  , and.**        
1b890 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f    [sqlite3_open_
1b8a0 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v2()] interfaces
1b8b0 20 63 72 65 61 74 65 20 61 20 6e 65 77 0a 2a 2a   create a new.**
1b8c0 20 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62            [datab
1b8d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1b8e0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
1b8f0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
1b900 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 67 69  database file gi
1b910 76 65 6e 20 69 6e 20 74 68 65 69 72 20 66 69 72  ven in their fir
1b920 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
1b930 0a 2a 2a 20 7b 48 31 32 37 30 32 7d 20 54 68 65  .** {H12702} The
1b940 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1b950 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  nt is interprete
1b960 64 20 61 73 20 55 54 46 2d 38 0a 2a 2a 20 20 20  d as UTF-8.**   
1b970 20 20 20 20 20 20 20 66 6f 72 20 5b 73 71 6c 69         for [sqli
1b980 74 65 33 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  te3_open()] and 
1b990 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1b9a0 28 29 5d 20 61 6e 64 20 61 73 20 55 54 46 2d 31  ()] and as UTF-1
1b9b0 36 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  6.**          in
1b9c0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1b9d0 20 6f 72 64 65 72 20 66 6f 72 20 5b 73 71 6c 69   order for [sqli
1b9e0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a  te3_open16()]..*
1b9f0 2a 0a 2a 2a 20 7b 48 31 32 37 30 33 7d 20 41 20  *.** {H12703} A 
1ba00 73 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63  successful invoc
1ba10 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1ba20 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
1ba30 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a  te3_open16()],.*
1ba40 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73  *          or [s
1ba50 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1ba60 5d 20 77 72 69 74 65 73 20 61 20 70 6f 69 6e 74  ] writes a point
1ba70 65 72 20 74 6f 20 61 20 6e 65 77 0a 2a 2a 20 20  er to a new.**  
1ba80 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73          [databas
1ba90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 6e  e connection] in
1baa0 74 6f 20 2a 70 70 44 62 2e 0a 2a 2a 0a 2a 2a 20  to *ppDb..**.** 
1bab0 7b 48 31 32 37 30 34 7d 20 54 68 65 20 5b 73 71  {H12704} The [sq
1bac0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1bad0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1bae0 5d 2c 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20  ], and.**       
1baf0 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e     [sqlite3_open
1bb00 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
1bb10 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
1bb20 5f 4f 4b 5d 20 75 70 6f 6e 20 73 75 63 63 65 73  _OK] upon succes
1bb30 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  s,.**          o
1bb40 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  r an appropriate
1bb50 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 6e   [error code] on
1bb60 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
1bb70 7b 48 31 32 37 30 36 7d 20 54 68 65 20 64 65 66  {H12706} The def
1bb80 61 75 6c 74 20 74 65 78 74 20 65 6e 63 6f 64 69  ault text encodi
1bb90 6e 67 20 66 6f 72 20 61 20 6e 65 77 20 64 61 74  ng for a new dat
1bba0 61 62 61 73 65 20 63 72 65 61 74 65 64 20 75 73  abase created us
1bbb0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
1bbc0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1bbd0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
1bbe0 6e 5f 76 32 28 29 5d 20 77 69 6c 6c 20 62 65 20  n_v2()] will be 
1bbf0 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  UTF-8..**.** {H1
1bc00 32 37 30 37 7d 20 54 68 65 20 64 65 66 61 75 6c  2707} The defaul
1bc10 74 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  t text encoding 
1bc20 66 6f 72 20 61 20 6e 65 77 20 64 61 74 61 62 61  for a new databa
1bc30 73 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  se created using
1bc40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1bc50 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
1bc60 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 2e 0a  will be UTF-16..
1bc70 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 39 7d 20 54  **.** {H12709} T
1bc80 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
1bc90 28 46 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65  (F,D)] interface
1bca0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
1bcb0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
1bcc0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46  qlite3_open_v2(F
1bcd0 2c 44 2c 47 2c 30 29 5d 20 77 68 65 72 65 20 74  ,D,G,0)] where t
1bce0 68 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 69  he G parameter i
1bcf0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  s.**          [S
1bd00 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1bd10 52 49 54 45 5d 7c 5b 53 51 4c 49 54 45 5f 4f 50  RITE]|[SQLITE_OP
1bd20 45 4e 5f 43 52 45 41 54 45 5d 2e 0a 2a 2a 0a 2a  EN_CREATE]..**.*
1bd30 2a 20 7b 48 31 32 37 31 31 7d 20 49 66 20 74 68  * {H12711} If th
1bd40 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e G parameter to
1bd50 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
1bd60 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74  2(F,D,G,V)] cont
1bd70 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ains the.**     
1bd80 20 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b       bit value [
1bd90 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1bda0 4f 4e 4c 59 5d 20 74 68 65 6e 20 74 68 65 20 64  ONLY] then the d
1bdb0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1bdc0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f  d.**          fo
1bdd0 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c 79 2e 0a  r reading only..
1bde0 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 32 7d 20 49  **.** {H12712} I
1bdf0 66 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65  f the G paramete
1be00 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r to [sqlite3_op
1be10 65 6e 5f 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20  en_v2(F,D,G,V)] 
1be20 63 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20  contains the.** 
1be30 20 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c           bit val
1be40 75 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ue [SQLITE_OPEN_
1be50 52 45 41 44 57 52 49 54 45 5d 20 74 68 65 6e 20  READWRITE] then 
1be60 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
1be70 6f 70 65 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20  opened.**       
1be80 20 20 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77     reading and w
1be90 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
1bea0 6c 65 2c 20 6f 72 20 66 6f 72 20 72 65 61 64 69  le, or for readi
1beb0 6e 67 20 6f 6e 6c 79 20 69 66 20 74 68 65 0a 2a  ng only if the.*
1bec0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 20  *          file 
1bed0 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
1bee0 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
1bef0 69 6e 67 20 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a  ing system..**.*
1bf00 2a 20 7b 48 31 32 37 31 33 7d 20 49 66 20 74 68  * {H12713} If th
1bf10 65 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e G parameter to
1bf20 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 76   [sqlite3_open(v
1bf30 32 28 46 2c 44 2c 47 2c 56 29 5d 20 6f 6d 69 74  2(F,D,G,V)] omit
1bf40 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
1bf50 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c    bit value [SQL
1bf60 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
1bf70 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
1bf80 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20  e does not.**   
1bf90 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 73 6c         previousl
1bfa0 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
1bfb0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
1bfc0 2a 0a 2a 2a 20 7b 48 31 32 37 31 34 7d 20 49 66  *.** {H12714} If
1bfd0 20 74 68 65 20 47 20 70 61 72 61 6d 65 74 65 72   the G parameter
1bfe0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
1bff0 6e 28 76 32 28 46 2c 44 2c 47 2c 56 29 5d 20 63  n(v2(F,D,G,V)] c
1c000 6f 6e 74 61 69 6e 73 20 74 68 65 0a 2a 2a 20 20  ontains the.**  
1c010 20 20 20 20 20 20 20 20 62 69 74 20 76 61 6c 75          bit valu
1c020 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
1c030 52 45 41 54 45 5d 20 61 6e 64 20 74 68 65 20 64  REATE] and the d
1c040 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
1c050 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 72 65  .**          pre
1c060 76 69 6f 75 73 6c 79 20 65 78 69 73 74 2c 20 74  viously exist, t
1c070 68 65 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hen an attempt i
1c080 73 20 6d 61 64 65 20 74 6f 20 63 72 65 61 74 65  s made to create
1c090 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
1c0a0 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   initialize the 
1c0b0 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20  database..**.** 
1c0c0 7b 48 31 32 37 31 37 7d 20 49 66 20 74 68 65 20  {H12717} If the 
1c0d0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1c0e0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
1c0f0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
1c100 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20  open16()],.**   
1c110 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
1c120 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 73  e3_open_v2()] is
1c130 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
1c140 6e 20 61 6e 20 70 72 69 76 61 74 65 2c 0a 2a 2a  n an private,.**
1c150 20 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65            epheme
1c160 72 61 6c 2c 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  ral, in-memory d
1c170 61 74 61 62 61 73 65 20 69 73 20 63 72 65 61 74  atabase is creat
1c180 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65  ed for the conne
1c190 63 74 69 6f 6e 2e 0a 2a 2a 20 20 20 20 20 20 20  ction..**       
1c1a0 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49     <todo>Is SQLI
1c1b0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53  TE_OPEN_CREATE|S
1c1c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1c1d0 52 49 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a  RITE required.**
1c1e0 20 20 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c            in sql
1c1f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c  ite3_open_v2()?<
1c200 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31  /todo>.**.** {H1
1c210 32 37 31 39 7d 20 49 66 20 74 68 65 20 66 69 6c  2719} If the fil
1c220 65 6e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 6f 72  ename is NULL or
1c230 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
1c240 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
1c250 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 70  ,.**          ep
1c260 68 65 6d 65 72 61 6c 20 6f 6e 2d 64 69 73 6b 20  hemeral on-disk 
1c270 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1c280 20 63 72 65 61 74 65 64 2e 0a 2a 2a 20 20 20 20   created..**    
1c290 20 20 20 20 20 20 3c 74 6f 64 6f 3e 49 73 20 53        <todo>Is S
1c2a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
1c2b0 45 7c 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  E|SQLITE_OPEN_RE
1c2c0 41 44 57 52 49 54 45 20 72 65 71 75 69 72 65 64  ADWRITE required
1c2d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
1c2e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1c2f0 29 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20  )?</todo>.**.** 
1c300 7b 48 31 32 37 32 31 7d 20 54 68 65 20 5b 64 61  {H12721} The [da
1c310 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c320 6e 5d 20 63 72 65 61 74 65 64 20 62 79 20 5b 73  n] created by [s
1c330 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46  qlite3_open_v2(F
1c340 2c 44 2c 47 2c 56 29 5d 0a 2a 2a 20 20 20 20 20  ,D,G,V)].**     
1c350 20 20 20 20 20 77 69 6c 6c 20 75 73 65 20 74 68       will use th
1c360 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
1c370 6f 62 6a 65 63 74 20 69 64 65 6e 74 69 66 69 65  object identifie
1c380 64 20 62 79 20 74 68 65 20 56 20 70 61 72 61 6d  d by the V param
1c390 65 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20  eter,.**        
1c3a0 20 20 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74    or the default
1c3b0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1c3c0 62 6a 65 63 74 20 69 66 20 56 20 69 73 20 61 20  bject if V is a 
1c3d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1c3e0 0a 2a 2a 20 7b 48 31 32 37 32 33 7d 20 54 77 6f  .** {H12723} Two
1c3f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c400 63 74 69 6f 6e 73 5d 20 77 69 6c 6c 20 73 68 61  ctions] will sha
1c410 72 65 20 61 20 63 6f 6d 6d 6f 6e 20 63 61 63 68  re a common cach
1c420 65 20 69 66 20 62 6f 74 68 20 77 65 72 65 0a 2a  e if both were.*
1c430 2a 20 20 20 20 20 20 20 20 20 20 6f 70 65 6e 65  *          opene
1c440 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  d with the same 
1c450 56 46 53 20 77 68 69 6c 65 20 5b 73 68 61 72 65  VFS while [share
1c460 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 77 61  d cache mode] wa
1c470 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 0a 2a 2a  s enabled and.**
1c480 20 20 20 20 20 20 20 20 20 20 69 66 20 62 6f 74            if bot
1c490 68 20 66 69 6c 65 6e 61 6d 65 73 20 63 6f 6d 70  h filenames comp
1c4a0 61 72 65 20 65 71 75 61 6c 20 75 73 69 6e 67 20  are equal using 
1c4b0 6d 65 6d 63 6d 70 28 29 20 61 66 74 65 72 20 68  memcmp() after h
1c4c0 61 76 69 6e 67 20 62 65 65 6e 0a 2a 2a 20 20 20  aving been.**   
1c4d0 20 20 20 20 20 20 20 70 72 6f 63 65 73 73 65 64         processed
1c4e0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
1c4f0 5f 76 66 73 20 7c 20 78 46 75 6c 6c 50 61 74 68  _vfs | xFullPath
1c500 6e 61 6d 65 5d 20 6d 65 74 68 6f 64 20 6f 66 20  name] method of 
1c510 74 68 65 20 56 46 53 2e 0a 2a 2f 0a 69 6e 74 20  the VFS..*/.int 
1c520 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
1c530 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
1c540 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
1c550 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
1c560 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
1c570 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
1c580 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
1c590 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
1c5a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
1c5b0 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
1c5c0 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
1c5d0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
1c5e0 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
1c5f0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
1c600 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
1c610 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
1c620 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
1c630 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
1c640 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
1c650 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
1c660 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
1c670 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
1c680 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
1c690 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
1c6a0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
1c6b0 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
1c6c0 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
1c6d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1c6e0 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
1c6f0 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
1c700 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
1c710 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c720 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
1c730 64 20 4d 65 73 73 61 67 65 73 20 7b 48 31 32 38  d Messages {H128
1c740 30 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 0a  00} <S60200>.**.
1c750 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
1c760 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61  rrcode() interfa
1c770 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
1c780 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63  umeric [result c
1c790 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
1c7a0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
1c7b0 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72  ] for the most r
1c7c0 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c  ecent failed sql
1c7d0 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a  ite3_* API call.
1c7e0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
1c7f0 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
1c800 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61  onnection]. If a
1c810 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20   prior API call 
1c820 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68  failed.** but th
1c830 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50  e most recent AP
1c840 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64  I call succeeded
1c850 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
1c860 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  ue from.** sqlit
1c870 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20  e3_errcode() is 
1c880 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
1c890 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72   The sqlite3_err
1c8a0 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
1c8b0 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
1c8c0 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
1c8d0 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
1c8e0 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
1c8f0 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
1c900 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
1c910 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
1c920 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * Memory to hold
1c930 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
1c940 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
1c950 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
1c960 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1c970 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
1c980 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
1c990 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
1c9a0 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
1c9b0 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
1c9c0 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
1c9d0 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
1c9e0 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
1c9f0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1ca00 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
1ca10 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
1ca20 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e  ..**.** If an in
1ca30 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69  terface fails wi
1ca40 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  th SQLITE_MISUSE
1ca50 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
1ca60 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61   interface.** wa
1ca70 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72  s invoked incorr
1ca80 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70  ectly by the app
1ca90 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68  lication.  In th
1caa0 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20  at case, the.** 
1cab0 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d  error code and m
1cac0 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61  essage may or ma
1cad0 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a  y not be set..**
1cae0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1caf0 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 31 7d 20 54  **.** {H12801} T
1cb00 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  he [sqlite3_errc
1cb10 6f 64 65 28 44 29 5d 20 69 6e 74 65 72 66 61 63  ode(D)] interfac
1cb20 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1cb30 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20  meric.**        
1cb40 20 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20    [result code] 
1cb50 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  or [extended res
1cb60 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
1cb70 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a  e most recently.
1cb80 2a 2a 20 20 20 20 20 20 20 20 20 20 66 61 69 6c  **          fail
1cb90 65 64 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c  ed interface cal
1cba0 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  l associated wit
1cbb0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
1cbc0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
1cbd0 2a 0a 2a 2a 20 7b 48 31 32 38 30 33 7d 20 54 68  *.** {H12803} Th
1cbe0 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  e [sqlite3_errms
1cbf0 67 28 44 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  g(D)] and [sqlit
1cc00 65 33 5f 65 72 72 6d 73 67 31 36 28 44 29 5d 0a  e3_errmsg16(D)].
1cc10 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65  **          inte
1cc20 72 66 61 63 65 73 20 72 65 74 75 72 6e 20 45 6e  rfaces return En
1cc30 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74  glish-language t
1cc40 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62  ext that describ
1cc50 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  es.**          t
1cc60 68 65 20 65 72 72 6f 72 20 69 6e 20 74 68 65 20  he error in the 
1cc70 6d 6f 73 74 6c 79 20 72 65 63 65 6e 74 6c 79 20  mostly recently 
1cc80 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63 65  failed interface
1cc90 20 63 61 6c 6c 2c 0a 2a 2a 20 20 20 20 20 20 20   call,.**       
1cca0 20 20 20 65 6e 63 6f 64 65 64 20 61 73 20 65 69     encoded as ei
1ccb0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
1ccc0 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
1ccd0 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 37  y..**.** {H12807
1cce0 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  } The strings re
1ccf0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1cd00 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64  e3_errmsg()] and
1cd10 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1cd20 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  16()].**        
1cd30 20 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69    are valid unti
1cd40 6c 20 74 68 65 20 6e 65 78 74 20 53 51 4c 69 74  l the next SQLit
1cd50 65 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c  e interface call
1cd60 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 38 7d  ..**.** {H12808}
1cd70 20 43 61 6c 6c 73 20 74 6f 20 41 50 49 20 72 6f   Calls to API ro
1cd80 75 74 69 6e 65 73 20 74 68 61 74 20 64 6f 20 6e  utines that do n
1cd90 6f 74 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72  ot return an err
1cda0 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20  or code.**      
1cdb0 20 20 20 20 28 65 78 61 6d 70 6c 65 3a 20 5b 73      (example: [s
1cdc0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
1cdd0 74 28 29 5d 29 20 64 6f 20 6e 6f 74 0a 2a 2a 20  t()]) do not.** 
1cde0 20 20 20 20 20 20 20 20 20 63 68 61 6e 67 65 20           change 
1cdf0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 6f  the error code o
1ce00 72 20 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e  r message return
1ce10 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
1ce20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f    [sqlite3_errco
1ce30 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  de()], [sqlite3_
1ce40 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73  errmsg()], or [s
1ce50 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
1ce60 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30  )]..**.** {H1280
1ce70 39 7d 20 49 6e 74 65 72 66 61 63 65 73 20 74 68  9} Interfaces th
1ce80 61 74 20 61 72 65 20 6e 6f 74 20 61 73 73 6f 63  at are not assoc
1ce90 69 61 74 65 64 20 77 69 74 68 20 61 20 73 70 65  iated with a spe
1cea0 63 69 66 69 63 0a 2a 2a 20 20 20 20 20 20 20 20  cific.**        
1ceb0 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e    [database conn
1cec0 65 63 74 69 6f 6e 5d 20 28 65 78 61 6d 70 6c 65  ection] (example
1ced0 73 3a 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  s:.**          [
1cee0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1cef0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
1cf00 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
1cf10 68 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  he()].**        
1cf20 20 20 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65 20    do not change 
1cf30 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
1cf40 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  ned by.**       
1cf50 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63     [sqlite3_errc
1cf60 6f 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ode()], [sqlite3
1cf70 5f 65 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b  _errmsg()], or [
1cf80 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1cf90 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1cfa0 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
1cfb0 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20  te3 *db);.const 
1cfc0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
1cfd0 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
1cfe0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1cff0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c  te3_errmsg16(sql
1d000 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1d010 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61  API3REF: SQL Sta
1d020 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48  tement Object {H
1d030 31 33 30 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a  13000} <H13010>.
1d040 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
1d050 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1d060 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
1d070 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
1d080 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
1d090 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
1d0a0 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
1d0b0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
1d0c0 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61  his object is va
1d0d0 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73  riously known as
1d0e0 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61   a "prepared sta
1d0f0 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20  tement" or a.** 
1d100 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
1d110 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
1d120 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
1d130 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  nt"..**.** The l
1d140 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
1d150 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
1d160 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
1d170 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
1d180 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
1d190 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
1d1a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1d1b0 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
1d1c0 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
1d1d0 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
1d1e0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73  d values to [hos
1d1f0 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73  t parameters] us
1d200 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
1d210 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
1d220 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
1d230 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
1d240 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
1d250 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
1d260 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
1d270 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
1d280 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  e statement usin
1d290 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
1d2a0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
1d2b0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
1d2c0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
1d2d0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
1d2e0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
1d2f0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
1d300 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
1d310 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
1d320 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  .**.** Refer to 
1d330 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
1d340 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68   individual meth
1d350 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64  ods above for ad
1d360 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
1d370 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  rmation..*/.type
1d380 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
1d390 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
1d3a0 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
1d3b0 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
1d3c0 4c 69 6d 69 74 73 20 7b 48 31 32 37 36 30 7d 20  Limits {H12760} 
1d3d0 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20600>.**.** T
1d3e0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
1d3f0 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
1d400 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
1d410 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
1d420 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
1d430 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
1d440 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
1d450 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
1d460 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
1d470 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
1d480 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
1d490 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
1d4a0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
1d4b0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
1d4c0 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
1d4d0 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
1d4e0 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
1d4f0 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
1d500 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
1d510 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
1d520 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
1d530 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
1d540 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
1d550 63 74 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f  ct.  The functio
1d560 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c  n returns the ol
1d570 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49  d limit..**.** I
1d580 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
1d590 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
1d5a0 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
1d5b0 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
1d5c0 20 46 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63   For the limit c
1d5d0 61 74 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54  ategory of SQLIT
1d5e0 45 5f 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72  E_LIMIT_XYZ ther
1d5f0 65 20 69 73 20 61 20 68 61 72 64 20 75 70 70 65  e is a hard uppe
1d600 72 0a 2a 2a 20 62 6f 75 6e 64 20 73 65 74 20 62  r.** bound set b
1d610 79 20 61 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  y a compile-time
1d620 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1d630 6d 61 63 72 6f 20 6e 61 6d 65 64 20 53 51 4c 49  macro named SQLI
1d640 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a 2a 2a 20 28  TE_MAX_XYZ..** (
1d650 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e  The "_LIMIT_" in
1d660 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61   the name is cha
1d670 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e  nged to "_MAX_".
1d680 29 0a 2a 2a 20 41 74 74 65 6d 70 74 73 20 74 6f  ).** Attempts to
1d690 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69   increase a limi
1d6a0 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64  t above its hard
1d6b0 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65   upper bound are
1d6c0 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75  .** silently tru
1d6d0 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61  ncated to the ha
1d6e0 72 64 20 75 70 70 65 72 20 6c 69 6d 69 74 2e 0a  rd upper limit..
1d6f0 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69 6d 65 20 6c  **.** Run time l
1d700 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
1d710 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
1d720 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
1d730 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
1d740 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
1d750 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
1d760 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
1d770 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
1d780 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
1d790 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
1d7a0 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
1d7b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
1d7c0 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 62 72 6f  t be a.** webbro
1d7d0 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
1d7e0 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
1d7f0 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
1d800 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
1d810 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
1d820 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
1d830 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
1d840 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
1d850 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
1d860 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
1d870 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
1d880 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
1d890 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
1d8a0 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
1d8b0 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
1d8c0 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
1d8d0 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
1d8e0 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
1d8f0 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
1d900 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
1d910 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
1d920 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
1d930 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
1d940 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
1d950 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1d960 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
1d970 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
1d980 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
1d990 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
1d9a0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
1d9b0 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
1d9c0 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
1d9d0 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
1d9e0 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
1d9f0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
1da00 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
1da10 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
1da20 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
1da30 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
1da40 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
1da50 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
1da60 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 32 7d  :.**.** {H12762}
1da70 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
1da80 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c  ll to [sqlite3_l
1da90 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20 77 68 65  imit(D,C,V)] whe
1daa0 72 65 20 56 20 69 73 0a 2a 2a 20 20 20 20 20 20  re V is.**      
1dab0 20 20 20 20 70 6f 73 69 74 69 76 65 20 63 68 61      positive cha
1dac0 6e 67 65 73 20 74 68 65 20 6c 69 6d 69 74 20 6f  nges the limit o
1dad0 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 63 6f  n the size of co
1dae0 6e 73 74 72 75 63 74 20 43 20 69 6e 20 74 68 65  nstruct C in the
1daf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
1db00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1db10 6e 5d 20 44 20 74 6f 20 74 68 65 20 6c 65 73 73  n] D to the less
1db20 65 72 20 6f 66 20 56 20 61 6e 64 20 74 68 65 20  er of V and the 
1db30 68 61 72 64 20 75 70 70 65 72 0a 2a 2a 20 20 20  hard upper.**   
1db40 20 20 20 20 20 20 20 62 6f 75 6e 64 20 6f 6e 20         bound on 
1db50 74 68 65 20 73 69 7a 65 20 6f 66 20 43 20 74 68  the size of C th
1db60 61 74 20 69 73 20 73 65 74 20 61 74 20 63 6f 6d  at is set at com
1db70 70 69 6c 65 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  pile-time..**.**
1db80 20 7b 48 31 32 37 36 36 7d 20 41 20 73 75 63 63   {H12766} A succ
1db90 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
1dba0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 44 2c  sqlite3_limit(D,
1dbb0 43 2c 56 29 5d 20 77 68 65 72 65 20 56 20 69 73  C,V)] where V is
1dbc0 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20   negative.**    
1dbd0 20 20 20 20 20 20 6c 65 61 76 65 73 20 74 68 65        leaves the
1dbe0 20 73 74 61 74 65 20 6f 66 20 74 68 65 20 5b 64   state of the [d
1dbf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1dc00 6f 6e 5d 20 44 20 75 6e 63 68 61 6e 67 65 64 2e  on] D unchanged.
1dc10 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 36 39 7d 20  .**.** {H12769} 
1dc20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
1dc30 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69  l to [sqlite3_li
1dc40 6d 69 74 28 44 2c 43 2c 56 29 5d 20 72 65 74 75  mit(D,C,V)] retu
1dc50 72 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rns the.**      
1dc60 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68 65      value of the
1dc70 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 73 69   limit on the si
1dc80 7a 65 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 20  ze of construct 
1dc90 43 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  C in the.**     
1dca0 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
1dcb0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 61 73 20  onnection] D as 
1dcc0 69 74 20 77 61 73 20 70 72 69 6f 72 20 74 6f 20  it was prior to 
1dcd0 74 68 65 20 63 61 6c 6c 2e 0a 2a 2f 0a 69 6e 74  the call..*/.int
1dce0 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
1dcf0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
1dd00 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
1dd10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1dd20 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
1dd30 74 65 67 6f 72 69 65 73 20 7b 48 31 32 37 39 30  tegories {H12790
1dd40 7d 20 3c 48 31 32 37 36 30 3e 0a 2a 2a 20 4b 45  } <H12760>.** KE
1dd50 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
1dd60 61 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20  ategory} {limit 
1dd70 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a  categories}.**.*
1dd80 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
1dd90 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
1dda0 20 61 73 70 65 63 74 73 20 6f 66 20 61 20 5b 64   aspects of a [d
1ddb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ddc0 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  on].** that can 
1ddd0 62 65 20 6c 69 6d 69 74 65 64 20 69 6e 20 73 69  be limited in si
1dde0 7a 65 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 5b  ze by calls to [
1ddf0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
1de00 2e 0a 2a 2a 20 54 68 65 20 6d 65 61 6e 69 6e 67  ..** The meaning
1de10 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
1de20 20 6c 69 6d 69 74 73 20 61 72 65 20 61 73 20 66   limits are as f
1de30 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64  ollows:.**.** <d
1de40 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
1de50 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
1de60 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1de70 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
1de80 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
1de90 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2e 3c 64   or table row.<d
1dea0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1deb0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
1dec0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1ded0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
1dee0 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
1def0 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a  atement.</dd>.**
1df00 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  .** <dt>SQLITE_L
1df10 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
1df20 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1df30 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
1df40 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
1df50 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
1df60 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
1df70 73 65 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20  set of a SELECT 
1df80 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
1df90 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1dfa0 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
1dfb0 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
1dfc0 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
1dfd0 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ause.</dd>.**.**
1dfe0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1dff0 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74  T_EXPR_DEPTH</dt
1e000 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1e010 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68  imum depth of th
1e020 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20  e parse tree on 
1e030 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c  any expression.<
1e040 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1e050 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
1e060 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
1e070 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1e080 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
1e090 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
1e0a0 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
1e0b0 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  nt.</dd>.**.** <
1e0c0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1e0d0 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
1e0e0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1e0f0 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
1e100 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
1e110 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
1e120 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
1e130 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
1e140 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a  statement.</dd>.
1e150 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1e160 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
1e170 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
1e180 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1e190 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
1e1a0 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
1e1b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
1e1c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
1e1d0 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HED</dt>.** <dd>
1e1e0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1e1f0 65 72 20 6f 66 20 61 74 74 61 63 68 65 64 20 64  er of attached d
1e200 61 74 61 62 61 73 65 73 2e 3c 2f 64 64 3e 0a 2a  atabases.</dd>.*
1e210 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1e220 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
1e230 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
1e240 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1e250 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
1e260 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
1e270 20 74 6f 20 74 68 65 20 4c 49 4b 45 20 6f 72 0a   to the LIKE or.
1e280 2a 2a 20 47 4c 4f 42 20 6f 70 65 72 61 74 6f 72  ** GLOB operator
1e290 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  s.</dd>.**.** <d
1e2a0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
1e2b0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f  ARIABLE_NUMBER</
1e2c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1e2d0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1e2e0 20 76 61 72 69 61 62 6c 65 73 20 69 6e 20 61 6e   variables in an
1e2f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1e300 68 61 74 20 63 61 6e 0a 2a 2a 20 62 65 20 62 6f  hat can.** be bo
1e310 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64  und.</dd>.** </d
1e320 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
1e330 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
1e340 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
1e350 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
1e360 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
1e370 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
1e380 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
1e390 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
1e3a0 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
1e3b0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
1e3c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
1e3d0 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
1e3e0 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
1e3f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
1e400 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
1e410 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
1e420 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1e430 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
1e440 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
1e450 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1e460 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
1e470 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
1e480 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1e490 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
1e4a0 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
1e4b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1e4c0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
1e4d0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
1e4e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1e4f0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
1e500 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
1e510 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e520 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
1e530 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33  L Statement {H13
1e540 30 31 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a  010} <S10000>.**
1e550 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
1e560 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
1e570 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65  er}.**.** To exe
1e580 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72  cute an SQL quer
1e590 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74  y, it must first
1e5a0 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74   be compiled int
1e5b0 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a  o a byte-code.**
1e5c0 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f   program using o
1e5d0 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ne of these rout
1e5e0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
1e5f0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
1e600 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
1e610 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1e620 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
1e630 0a 2a 2a 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  .** prior call t
1e640 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
1e650 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
1e660 6e 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  n_v2()] or [sqli
1e670 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a  te3_open16()]..*
1e680 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
1e690 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
1e6a0 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
1e6b0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
1e6c0 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
1e6d0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
1e6e0 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
1e6f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
1e700 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1e710 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
1e720 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
1e730 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
1e740 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
1e750 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1e760 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
1e770 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  16..**.** If the
1e780 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
1e790 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
1e7a0 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  o, then zSql is 
1e7b0 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
1e7c0 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
1e7d0 6d 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79 74  minator. If nByt
1e7e0 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
1e7f0 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
1e800 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d  e maximum.** num
1e810 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65  ber of  bytes re
1e820 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 57  ad from zSql.  W
1e830 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  hen nByte is non
1e840 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a  -negative, the.*
1e850 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e  * zSql string en
1e860 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65  ds at either the
1e870 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72   first '\000' or
1e880 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63   '\u0000' charac
1e890 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42  ter or.** the nB
1e8a0 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69  yte-th byte, whi
1e8b0 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
1e8c0 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65  st. If the calle
1e8d0 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20  r knows.** that 
1e8e0 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72  the supplied str
1e8f0 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69  ing is nul-termi
1e900 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72  nated, then ther
1e910 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20  e is a small.** 
1e920 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61  performance adva
1e930 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e  ntage to be gain
1e940 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e  ed by passing an
1e950 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
1e960 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61   that.** is equa
1e970 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20  l to the number 
1e980 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
1e990 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
1e9a0 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
1e9b0 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
1e9c0 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a  tor bytes..**.**
1e9d0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65   *pzTail is made
1e9e0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
1e9f0 20 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74   first byte past
1ea00 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 0a   the end of the.
1ea10 2a 2a 20 66 69 72 73 74 20 53 51 4c 20 73 74 61  ** first SQL sta
1ea20 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20  tement in zSql. 
1ea30 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1ea40 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65 20 74 68 65  only compile the
1ea50 20 66 69 72 73 74 0a 2a 2a 20 73 74 61 74 65 6d   first.** statem
1ea60 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20  ent in zSql, so 
1ea70 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20  *pzTail is left 
1ea80 70 6f 69 6e 74 69 6e 67 20 74 6f 20 77 68 61 74  pointing to what
1ea90 20 72 65 6d 61 69 6e 73 0a 2a 2a 20 75 6e 63 6f   remains.** unco
1eaa0 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70  mpiled..**.** *p
1eab0 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
1eac0 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
1ead0 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
1eae0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
1eaf0 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
1eb00 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1eb10 5f 73 74 65 70 28 29 5d 2e 20 20 49 66 20 74 68  _step()].  If th
1eb20 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
1eb30 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
1eb40 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 49 66 20  ** to NULL.  If 
1eb50 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
1eb60 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
1eb70 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
1eb80 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
1eb90 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
1eba0 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
1ebb0 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
1ebc0 20 7b 41 31 33 30 31 38 7d 20 54 68 65 20 63 61   {A13018} The ca
1ebd0 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
1ebe0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
1ebf0 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
1ec00 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
1ec10 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
1ec20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1ec30 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
1ec40 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1ec50 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63  it..**.** On suc
1ec60 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  cess, [SQLITE_OK
1ec70 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2c 20 6f  ] is returned, o
1ec80 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
1ec90 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
1eca0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
1ecb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1ecc0 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
1ecd0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
1ece0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
1ecf0 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
1ed00 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
1ed10 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
1ed20 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
1ed30 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
1ed40 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1ed50 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
1ed60 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
1ed70 75 72 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68  uraged..** In th
1ed80 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
1ed90 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
1eda0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
1edb0 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
1edc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
1edd0 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
1ede0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
1edf0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
1ee00 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
1ee10 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
1ee20 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
1ee30 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61  e to.** behave a
1ee40 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
1ee50 74 77 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  two ways:.**.** 
1ee60 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
1ee70 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1ee80 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
1ee90 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
1eea0 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
1eeb0 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
1eec0 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
1eed0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1eee0 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
1eef0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
1ef00 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
1ef10 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
1ef20 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66  un it again.  If
1ef30 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20   the schema has 
1ef40 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20  changed in.** a 
1ef50 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74  way that makes t
1ef60 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20  he statement no 
1ef70 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73  longer valid, [s
1ef80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1ef90 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74  ill still.** ret
1efa0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  urn [SQLITE_SCHE
1efb0 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65  MA].  But unlike
1efc0 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   the legacy beha
1efd0 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43  vior, [SQLITE_SC
1efe0 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20  HEMA] is.** now 
1eff0 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20  a fatal error.  
1f000 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  Calling [sqlite3
1f010 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1f020 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61  gain will not ma
1f030 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  ke the.** error 
1f040 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20  go away.  Note: 
1f050 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  use [sqlite3_err
1f060 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74  msg()] to find t
1f070 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68  he text.** of th
1f080 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20  e parsing error 
1f090 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20  that results in 
1f0a0 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  an [SQLITE_SCHEM
1f0b0 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f  A] return..** </
1f0c0 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
1f0d0 2a 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20  * When an error 
1f0e0 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
1f0f0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
1f100 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
1f110 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
1f120 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
1f130 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
1f140 65 73 5d 2e 20 20 54 68 65 20 6c 65 67 61 63 79  es].  The legacy
1f150 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
1f160 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  at.** [sqlite3_s
1f170 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
1f180 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
1f190 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
1f1a0 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a  ] result code.**
1f1b0 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68   and you would h
1f1c0 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65  ave to make a se
1f1d0 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cond call to [sq
1f1e0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69  lite3_reset()] i
1f1f0 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69  n order.** to fi
1f200 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
1f210 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  g cause of the p
1f220 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65  roblem. With the
1f230 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a   "v2" prepare.**
1f240 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
1f250 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
1f260 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
1f270 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
1f280 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
1f290 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  i>.** </ol>.**.*
1f2a0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1f2b0 0a 2a 2a 20 7b 48 31 33 30 31 31 7d 20 54 68 65  .** {H13011} The
1f2c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f2d0 65 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29 5d 20  e(db,zSql,...)] 
1f2e0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
1f2f0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f300 5f 76 32 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29  _v2(db,zSql,...)
1f310 5d 20 69 6e 74 65 72 66 61 63 65 73 20 69 6e 74  ] interfaces int
1f320 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 20 20  erpret the.**   
1f330 20 20 20 20 20 20 20 74 65 78 74 20 69 6e 20 74         text in t
1f340 68 65 69 72 20 7a 53 71 6c 20 70 61 72 61 6d 65  heir zSql parame
1f350 74 65 72 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a  ter as UTF-8..**
1f360 0a 2a 2a 20 7b 48 31 33 30 31 32 7d 20 54 68 65  .** {H13012} The
1f370 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f380 65 31 36 28 64 62 2c 7a 53 71 6c 2c 2e 2e 2e 29  e16(db,zSql,...)
1f390 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  ] and.**        
1f3a0 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61    [sqlite3_prepa
1f3b0 72 65 31 36 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  re16_v2(db,zSql,
1f3c0 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73  ...)] interfaces
1f3d0 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a   interpret the.*
1f3e0 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20  *          text 
1f3f0 69 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61  in their zSql pa
1f400 72 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 31  rameter as UTF-1
1f410 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
1f420 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
1f430 2a 20 7b 48 31 33 30 31 33 7d 20 49 66 20 74 68  * {H13013} If th
1f440 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
1f450 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
1f460 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  pare_v2(db,zSql,
1f470 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  nByte,...)].**  
1f480 20 20 20 20 20 20 20 20 61 6e 64 20 69 74 73 20          and its 
1f490 76 61 72 69 61 6e 74 73 20 69 73 20 6c 65 73 73  variants is less
1f4a0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 20   than zero, the 
1f4b0 53 51 4c 20 74 65 78 74 20 69 73 0a 2a 2a 20 20  SQL text is.**  
1f4c0 20 20 20 20 20 20 20 20 72 65 61 64 20 66 72 6f          read fro
1f4d0 6d 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  m zSql is read u
1f4e0 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
1f4f0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
1f500 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 34 7d 20 49  **.** {H13014} I
1f510 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
1f520 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
1f530 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a  _prepare_v2(db,z
1f540 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a  Sql,nByte,...)].
1f550 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
1f560 69 74 73 20 76 61 72 69 61 6e 74 73 20 69 73 20  its variants is 
1f570 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
1f580 65 6e 20 61 74 20 6d 6f 73 74 20 6e 42 79 74 65  en at most nByte
1f590 73 20 62 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20  s bytes of.**   
1f5a0 20 20 20 20 20 20 20 53 51 4c 20 74 65 78 74 20         SQL text 
1f5b0 69 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  is read from zSq
1f5c0 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 35  l..**.** {H13015
1f5d0 7d 20 49 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  } In [sqlite3_pr
1f5e0 65 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c  epare_v2(db,zSql
1f5f0 2c 4e 2c 50 2c 70 7a 54 61 69 6c 29 5d 20 61 6e  ,N,P,pzTail)] an
1f600 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 0a 2a  d its variants.*
1f610 2a 20 20 20 20 20 20 20 20 20 20 69 66 20 74 68  *          if th
1f620 65 20 7a 53 71 6c 20 69 6e 70 75 74 20 74 65 78  e zSql input tex
1f630 74 20 63 6f 6e 74 61 69 6e 73 20 6d 6f 72 65 20  t contains more 
1f640 74 68 61 6e 20 6f 6e 65 20 53 51 4c 20 73 74 61  than one SQL sta
1f650 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20  tement.**       
1f660 20 20 20 61 6e 64 20 70 7a 54 61 69 6c 20 69 73     and pzTail is
1f670 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
1f680 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
1f690 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 0a  to point to the.
1f6a0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 72 73  **          firs
1f6b0 74 20 62 79 74 65 20 70 61 73 74 20 74 68 65 20  t byte past the 
1f6c0 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
1f6d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1f6e0 6e 20 7a 53 71 6c 2e 0a 2a 2a 20 20 20 20 20 20  n zSql..**      
1f6f0 20 20 20 20 3c 74 6f 64 6f 3e 57 68 61 74 20 64      <todo>What d
1f700 6f 65 73 20 2a 70 7a 54 61 69 6c 20 70 6f 69 6e  oes *pzTail poin
1f710 74 20 74 6f 20 69 66 20 74 68 65 72 65 20 69 73  t to if there is
1f720 20 6f 6e 65 20 73 74 61 74 65 6d 65 6e 74 3f 3c   one statement?<
1f730 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31  /todo>.**.** {H1
1f740 33 30 31 36 7d 20 41 20 73 75 63 63 65 73 73 66  3016} A successf
1f750 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
1f760 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64  te3_prepare_v2(d
1f770 62 2c 7a 53 71 6c 2c 4e 2c 70 70 53 74 6d 74 2c  b,zSql,N,ppStmt,
1f780 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ...)].**        
1f790 20 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20    or one of its 
1f7a0 76 61 72 69 61 6e 74 73 20 77 72 69 74 65 73 20  variants writes 
1f7b0 69 6e 74 6f 20 2a 70 70 53 74 6d 74 20 61 20 70  into *ppStmt a p
1f7c0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 77 0a  ointer to a new.
1f7d0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
1f7e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1f7f0 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   or a pointer to
1f800 20 4e 55 4c 4c 20 69 66 20 7a 53 71 6c 20 63 6f   NULL if zSql co
1f810 6e 74 61 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20  ntains.**       
1f820 20 20 20 6e 6f 74 68 69 6e 67 20 6f 74 68 65 72     nothing other
1f830 20 74 68 61 6e 20 77 68 69 74 65 73 70 61 63 65   than whitespace
1f840 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 2e 0a 2a 2a   or comments..**
1f850 0a 2a 2a 20 7b 48 31 33 30 31 39 7d 20 54 68 65  .** {H13019} The
1f860 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f870 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  e_v2()] interfac
1f880 65 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  e and its varian
1f890 74 73 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20  ts return.**    
1f8a0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f 4b        [SQLITE_OK
1f8b0 5d 20 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69  ] or an appropri
1f8c0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
1f8d0 20 75 70 6f 6e 20 66 61 69 6c 75 72 65 2e 0a 2a   upon failure..*
1f8e0 2a 0a 2a 2a 20 7b 48 31 33 30 32 31 7d 20 42 65  *.** {H13021} Be
1f8f0 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  fore [sqlite3_pr
1f900 65 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 6e 42  epare(db,zSql,nB
1f910 79 74 65 2c 70 70 53 74 6d 74 2c 70 7a 54 61 69  yte,ppStmt,pzTai
1f920 6c 29 5d 20 6f 72 20 69 74 73 0a 2a 2a 20 20 20  l)] or its.**   
1f930 20 20 20 20 20 20 20 76 61 72 69 61 6e 74 73 20         variants 
1f940 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72  returns an error
1f950 20 28 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65   (any value othe
1f960 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
1f970 4b 5d 29 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  K]),.**         
1f980 20 74 68 65 79 20 66 69 72 73 74 20 73 65 74 20   they first set 
1f990 2a 70 70 53 74 6d 74 20 74 6f 20 4e 55 4c 4c 2e  *ppStmt to NULL.
1f9a0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1f9b0 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
1f9c0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1f9d0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1f9e0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1f9f0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1fa00 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1fa10 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
1fa20 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1fa30 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1fa40 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1fa50 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1fa60 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1fa70 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1fa80 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1fa90 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1faa0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
1fab0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1fac0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1fad0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1fae0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1faf0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
1fb00 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1fb10 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1fb20 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1fb30 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1fb40 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1fb50 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
1fb60 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1fb70 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1fb80 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1fb90 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1fba0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1fbb0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1fbc0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1fbd0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1fbe0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1fbf0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1fc00 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1fc10 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1fc20 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
1fc30 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1fc40 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
1fc50 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1fc60 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1fc70 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1fc80 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1fc90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1fca0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
1fcb0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1fcc0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1fcd0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1fce0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1fcf0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1fd00 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1fd10 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1fd20 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1fd30 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
1fd40 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1fd50 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1fd60 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1fd70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
1fd80 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73  repare16_v2(.  s
1fd90 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1fda0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
1fdb0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
1fdc0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
1fdd0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
1fde0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
1fdf0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1fe00 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1fe10 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1fe20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1fe30 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1fe40 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1fe50 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1fe60 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1fe70 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
1fe80 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1fe90 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1fea0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1feb0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   zSql */.);../*.
1fec0 2a 2a 20 43 41 50 49 52 45 46 3a 20 52 65 74 72  ** CAPIREF: Retr
1fed0 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
1fee0 20 53 51 4c 20 7b 48 31 33 31 30 30 7d 20 3c 48   SQL {H13100} <H
1fef0 31 33 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  13000>.**.** Thi
1ff00 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
1ff10 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
1ff20 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
1ff30 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
1ff40 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
1ff50 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
1ff60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1ff70 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
1ff80 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
1ff90 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
1ffa0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1ffb0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
1ffc0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1ffd0 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  2()]..**.** INVA
1ffe0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
1fff0 31 33 31 30 31 7d 20 49 66 20 74 68 65 20 5b 70  13101} If the [p
20000 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20010 74 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65  t] passed as the
20020 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
20030 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
20040 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63 6f 6d  3_sql()] was com
20050 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
20060 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
20070 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  are_v2()] or.** 
20080 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
20090 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
200a0 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ], then [sqlite3
200b0 5f 73 71 6c 28 29 5d 20 72 65 74 75 72 6e 73 0a  _sql()] returns.
200c0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 6f  **          a po
200d0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
200e0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
200f0 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20 55  g containing a U
20100 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 0a 2a  TF-8 rendering.*
20110 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
20120 65 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 73  e original SQL s
20130 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
20140 7b 48 31 33 31 30 32 7d 20 49 66 20 74 68 65 20  {H13102} If the 
20150 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
20160 65 6e 74 5d 20 70 61 73 73 65 64 20 61 73 20 74  ent] passed as t
20170 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
20180 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
20190 74 65 33 5f 73 71 6c 28 29 5d 20 77 61 73 20 63  te3_sql()] was c
201a0 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
201b0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
201c0 65 70 61 72 65 28 29 5d 20 6f 72 0a 2a 2a 20 20  epare()] or.**  
201d0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
201e0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
201f0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c  hen [sqlite3_sql
20200 28 29 5d 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ()] returns a NU
20210 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
20220 2a 20 7b 48 31 33 31 30 33 7d 20 54 68 65 20 73  * {H13103} The s
20230 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62  tring returned b
20240 79 20 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 53  y [sqlite3_sql(S
20250 29 5d 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  )] is valid unti
20260 6c 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  l the.**        
20270 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
20280 65 6d 65 6e 74 5d 20 53 20 69 73 20 64 65 6c 65  ement] S is dele
20290 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
202a0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 2e  e3_finalize(S)].
202b0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
202c0 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
202d0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
202e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
202f0 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
20300 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
20310 74 20 7b 48 31 35 30 30 30 7d 20 3c 53 32 30 32  t {H15000} <S202
20320 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
20330 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
20340 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
20350 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
20360 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
20370 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
20380 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
20390 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
203a0 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
203b0 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
203c0 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
203d0 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
203e0 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
203f0 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
20400 73 20 69 74 20 73 74 6f 72 65 73 2e 20 56 61 6c  s it stores. Val
20410 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
20420 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
20430 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
20440 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
20450 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
20460 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
20470 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
20480 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
20490 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
204a0 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
204b0 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
204c0 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
204d0 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
204e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
204f0 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
20500 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
20510 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
20520 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
20530 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
20540 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
20550 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
20560 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
20570 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
20580 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
20590 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
205a0 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
205b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
205c0 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
205d0 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
205e0 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
205f0 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
20600 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
20610 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
20620 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75  .  A internal mu
20630 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
20640 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
20650 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
20660 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
20670 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
20680 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
20690 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
206a0 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
206b0 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
206c0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
206d0 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
206e0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
206f0 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
20700 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
20710 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
20720 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
20730 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
20740 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
20750 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
20760 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
20770 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
20780 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
20790 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
207a0 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
207b0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
207c0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
207d0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
207e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
207f0 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
20800 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
20810 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
20820 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
20830 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
20840 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
20850 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
20860 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
20870 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
20880 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20  between between 
20890 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
208a0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
208b0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
208c0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
208d0 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
208e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
208f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
20900 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
20910 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
20920 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
20930 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
20940 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
20950 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
20960 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
20970 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  d..** The sqlite
20980 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
20990 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
209a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
209b0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
209c0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
209d0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
209e0 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
209f0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
20a00 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
20a10 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
20a20 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
20a30 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
20a40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
20a50 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
20a60 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
20a70 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
20a80 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
20a90 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
20aa0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
20ab0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
20ac0 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
20ad0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
20ae0 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
20af0 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 20   Context Object 
20b00 7b 48 31 36 30 30 31 7d 20 3c 53 32 30 32 30 30  {H16001} <S20200
20b10 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  >.**.** The cont
20b20 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
20b30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
20b40 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
20b50 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
20b60 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
20b70 20 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61    A pointer to a
20b80 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
20b90 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
20ba0 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
20bb0 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
20bc0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
20bd0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
20be0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
20bf0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
20c00 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
20c10 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
20c20 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
20c30 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
20c40 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
20c50 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
20c60 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
20c70 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
20c80 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
20c90 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
20ca0 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
20cb0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
20cc0 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
20cd0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
20ce0 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
20cf0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
20d00 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
20d10 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
20d20 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
20d30 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
20d40 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
20d50 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
20d60 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 20 7b  red Statements {
20d70 48 31 33 35 30 30 7d 20 3c 53 37 30 33 30 30 3e  H13500} <S70300>
20d80 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
20d90 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
20da0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
20db0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
20dc0 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
20dd0 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
20de0 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
20df0 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
20e00 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 49  binding}.**.** I
20e10 6e 20 74 68 65 20 53 51 4c 20 73 74 72 69 6e 67  n the SQL string
20e20 73 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  s input to [sqli
20e30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
20e40 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
20e50 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
20e60 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
20e70 62 79 20 61 20 70 61 72 61 6d 65 74 65 72 20 69  by a parameter i
20e80 6e 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 66  n one of these f
20e90 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  orms:.**.** <ul>
20ea0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
20eb0 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
20ec0 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
20ed0 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
20ee0 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
20ef0 2a 2a 20 49 6e 20 74 68 65 20 70 61 72 61 6d 65  ** In the parame
20f00 74 65 72 20 66 6f 72 6d 73 20 73 68 6f 77 6e 20  ter forms shown 
20f10 61 62 6f 76 65 20 4e 4e 4e 20 69 73 20 61 6e 20  above NNN is an 
20f20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
20f30 0a 2a 2a 20 61 6e 64 20 56 56 56 20 69 73 20 61  .** and VVV is a
20f40 6e 20 61 6c 70 68 61 2d 6e 75 6d 65 72 69 63 20  n alpha-numeric 
20f50 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 2e 20  parameter name. 
20f60 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68  The values of th
20f70 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ese.** parameter
20f80 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
20f90 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
20fa0 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61  ames" or "SQL pa
20fb0 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61  rameters").** ca
20fc0 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74  n be set using t
20fd0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
20fe0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66  *() routines def
20ff0 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ined here..**.**
21000 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
21010 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
21020 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
21030 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
21040 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
21050 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
21060 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
21070 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
21080 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
21090 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
210a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
210b0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
210c0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
210d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
210e0 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20   be set..** The 
210f0 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
21100 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
21110 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20  dex of 1.  When 
21120 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
21130 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
21140 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
21150 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
21160 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
21170 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
21180 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
21190 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
211a0 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65  currence..** The
211b0 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
211c0 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
211d0 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
211e0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
211f0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
21200 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
21210 66 20 64 65 73 69 72 65 64 2e 20 20 54 68 65 20  f desired.  The 
21220 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
21230 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
21240 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
21250 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76  NN..** The NNN v
21260 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
21270 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
21280 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
21290 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
212a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
212b0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
212c0 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
212d0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  )..**.** The thi
212e0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
212f0 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
21300 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
21310 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73  r..**.** In thos
21320 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
21330 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
21340 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
21350 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
21360 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
21370 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
21380 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
21390 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
213a0 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
213b0 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
213c0 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
213d0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
213e0 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  s..** If the fou
213f0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
21400 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c   negative, the l
21410 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
21420 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
21430 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
21440 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
21450 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
21460 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61  *.** The fifth a
21470 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
21480 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20  e3_bind_blob(), 
21490 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
214a0 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  t(), and.** sqli
214b0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
214c0 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  ) is a destructo
214d0 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
214e0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
214f0 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
21500 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
21510 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 49 66  shed with it. If
21520 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
21530 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
21540 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
21550 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
21560 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
21570 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
21580 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
21590 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
215a0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
215b0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
215c0 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  reed..** If the 
215d0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
215e0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
215f0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
21600 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
21610 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
21620 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
21630 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
21640 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
21650 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
21660 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
21670 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ns..**.** The sq
21680 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
21690 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
216a0 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
216b0 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
216c0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
216d0 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f  roes.  A zeroblo
216e0 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
216f0 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
21700 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
21710 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
21720 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
21730 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
21740 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
21750 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
21760 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
21770 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
21780 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
21790 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
217a0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
217b0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
217c0 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
217d0 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
217e0 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 76 61  ** A negative va
217f0 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
21800 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
21810 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
21820 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  OB..**.** The sq
21830 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
21840 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
21850 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20  called after.** 
21860 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21870 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20  _v2()] (and its 
21880 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71  variants) or [sq
21890 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
218a0 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71  nd.** before [sq
218b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
218c0 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e  * Bindings are n
218d0 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
218e0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
218f0 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
21900 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
21910 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
21920 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
21930 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
21940 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
21950 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
21960 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20  r an error code 
21970 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67  if.** anything g
21980 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c  oes wrong.  [SQL
21990 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
219a0 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
219b0 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
219c0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
219d0 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  .  [SQLITE_NOMEM
219e0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
219f0 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
21a00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
21a10 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  SE] might be ret
21a20 75 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72  urned if these r
21a30 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
21a40 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75  ed on a.** virtu
21a50 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20  al machine that 
21a60 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61  is the wrong sta
21a70 74 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20  te or which has 
21a80 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e  already been fin
21a90 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63  alized..** Detec
21aa0 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69  tion of misuse i
21ab0 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41  s unreliable.  A
21ac0 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
21ad0 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a  ld not depend.**
21ae0 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   on SQLITE_MISUS
21af0 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49  E returns.  SQLI
21b00 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74  TE_MISUSE is int
21b10 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74  ended to indicat
21b20 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65  e a.** a logic e
21b30 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c  rror in the appl
21b40 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65  ication.  Future
21b50 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
21b60 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e  ite might.** pan
21b70 69 63 20 72 61 74 68 65 72 20 74 68 61 6e 20 72  ic rather than r
21b80 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
21b90 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  USE..**.** See a
21ba0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
21bb0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
21bc0 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nt()],.** [sqlit
21bd0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
21be0 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b  r_name()], and [
21bf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
21c00 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
21c10 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
21c20 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 30 36  S:.**.** {H13506
21c30 7d 20 54 68 65 20 5b 53 51 4c 20 73 74 61 74 65  } The [SQL state
21c40 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 5d 20 72  ment compiler] r
21c50 65 63 6f 67 6e 69 7a 65 73 20 74 6f 6b 65 6e 73  ecognizes tokens
21c60 20 6f 66 20 74 68 65 20 66 6f 72 6d 73 0a 2a 2a   of the forms.**
21c70 20 20 20 20 20 20 20 20 20 20 22 3f 22 2c 20 22            "?", "
21c80 3f 4e 4e 4e 22 2c 20 22 24 56 56 56 22 2c 20 22  ?NNN", "$VVV", "
21c90 3a 56 56 56 22 2c 20 61 6e 64 20 22 40 56 56 56  :VVV", and "@VVV
21ca0 22 20 61 73 20 53 51 4c 20 70 61 72 61 6d 65 74  " as SQL paramet
21cb0 65 72 73 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ers,.**         
21cc0 20 77 68 65 72 65 20 4e 4e 4e 20 69 73 20 61 6e   where NNN is an
21cd0 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e  y sequence of on
21ce0 65 20 6f 72 20 6d 6f 72 65 20 64 69 67 69 74 73  e or more digits
21cf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
21d00 20 77 68 65 72 65 20 56 56 56 20 69 73 20 61 6e   where VVV is an
21d10 79 20 73 65 71 75 65 6e 63 65 20 6f 66 20 6f 6e  y sequence of on
21d20 65 20 6f 72 20 6d 6f 72 65 20 61 6c 70 68 61 6e  e or more alphan
21d30 75 6d 65 72 69 63 0a 2a 2a 20 20 20 20 20 20 20  umeric.**       
21d40 20 20 20 63 68 61 72 61 63 74 65 72 73 20 6f 72     characters or
21d50 20 22 3a 3a 22 20 6f 70 74 69 6f 6e 61 6c 6c 79   "::" optionally
21d60 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 61 20 73   followed by a s
21d70 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
21d80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 6f 20  .**          no 
21d90 73 70 61 63 65 73 20 61 6e 64 20 63 6f 6e 74 61  spaces and conta
21da0 69 6e 65 64 20 77 69 74 68 69 6e 20 70 61 72 65  ined within pare
21db0 6e 74 68 65 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b  ntheses..**.** {
21dc0 48 31 33 35 30 39 7d 20 54 68 65 20 69 6e 69 74  H13509} The init
21dd0 69 61 6c 20 76 61 6c 75 65 20 6f 66 20 61 6e 20  ial value of an 
21de0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
21df0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   NULL..**.** {H1
21e00 33 35 31 32 7d 20 54 68 65 20 69 6e 64 65 78 20  3512} The index 
21e10 6f 66 20 61 6e 20 22 3f 22 20 53 51 4c 20 70 61  of an "?" SQL pa
21e20 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6c  rameter is one l
21e30 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 0a 2a  arger than the.*
21e40 2a 20 20 20 20 20 20 20 20 20 20 6c 61 72 67 65  *          large
21e50 73 74 20 69 6e 64 65 78 20 6f 66 20 53 51 4c 20  st index of SQL 
21e60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
21e70 20 6c 65 66 74 2c 20 6f 72 20 31 20 69 66 0a 2a   left, or 1 if.*
21e80 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 22  *          the "
21e90 3f 22 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f  ?" is the leftmo
21ea0 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
21eb0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 31 35 7d  ..**.** {H13515}
21ec0 20 54 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   The index of an
21ed0 20 22 3f 4e 4e 4e 22 20 53 51 4c 20 70 61 72 61   "?NNN" SQL para
21ee0 6d 65 74 65 72 20 69 73 20 74 68 65 20 69 6e 74  meter is the int
21ef0 65 67 65 72 20 4e 4e 4e 2e 0a 2a 2a 0a 2a 2a 20  eger NNN..**.** 
21f00 7b 48 31 33 35 31 38 7d 20 54 68 65 20 69 6e 64  {H13518} The ind
21f10 65 78 20 6f 66 20 61 6e 20 22 3a 56 56 56 22 2c  ex of an ":VVV",
21f20 20 22 24 56 56 56 22 2c 20 6f 72 20 22 40 56 56   "$VVV", or "@VV
21f30 56 22 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  V" SQL parameter
21f40 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
21f50 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20  the same as the 
21f60 69 6e 64 65 78 20 6f 66 20 6c 65 66 74 6d 6f 73  index of leftmos
21f70 74 20 6f 63 63 75 72 72 65 6e 63 65 73 20 6f 66  t occurrences of
21f80 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20   the same.**    
21f90 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2c        parameter,
21fa0 20 6f 72 20 6f 6e 65 20 6d 6f 72 65 20 74 68 61   or one more tha
21fb0 6e 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e  n the largest in
21fc0 64 65 78 20 6f 76 65 72 20 61 6c 6c 0a 2a 2a 20  dex over all.** 
21fd0 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74           paramet
21fe0 65 72 73 20 74 6f 20 74 68 65 20 6c 65 66 74 20  ers to the left 
21ff0 69 66 20 74 68 69 73 20 69 73 20 74 68 65 20 66  if this is the f
22000 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 0a  irst occurrence.
22010 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  **          of t
22020 68 69 73 20 70 61 72 61 6d 65 74 65 72 2c 20 6f  his parameter, o
22030 72 20 31 20 69 66 20 74 68 69 73 20 69 73 20 74  r 1 if this is t
22040 68 65 20 6c 65 66 74 6d 6f 73 74 20 70 61 72 61  he leftmost para
22050 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  meter..**.** {H1
22060 33 35 32 31 7d 20 54 68 65 20 5b 53 51 4c 20 73  3521} The [SQL s
22070 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
22080 72 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  r] fails with an
22090 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 0a   [SQLITE_RANGE].
220a0 2a 2a 20 20 20 20 20 20 20 20 20 20 65 72 72 6f  **          erro
220b0 72 20 69 66 20 74 68 65 20 69 6e 64 65 78 20 6f  r if the index o
220c0 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
220d0 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  er is less than 
220e0 31 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  1.**          or
220f0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68   greater than th
22100 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 53  e compile-time S
22110 51 4c 49 54 45 5f 4d 41 58 5f 56 41 52 49 41 42  QLITE_MAX_VARIAB
22120 4c 45 5f 4e 55 4d 42 45 52 0a 2a 2a 20 20 20 20  LE_NUMBER.**    
22130 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 2e        parameter.
22140 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 34 7d 20  .**.** {H13524} 
22150 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  Calls to [sqlite
22160 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71  3_bind_text | sq
22170 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 56  lite3_bind(S,N,V
22180 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,...)].**       
22190 20 20 20 61 73 73 6f 63 69 61 74 65 20 74 68 65     associate the
221a0 20 76 61 6c 75 65 20 56 20 77 69 74 68 20 61 6c   value V with al
221b0 6c 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  l SQL parameters
221c0 20 68 61 76 69 6e 67 20 61 6e 0a 2a 2a 20 20 20   having an.**   
221d0 20 20 20 20 20 20 20 69 6e 64 65 78 20 6f 66 20         index of 
221e0 4e 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  N in the [prepar
221f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
22200 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 32 37 7d 20  .**.** {H13527} 
22210 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  Calls to [sqlite
22220 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 73 71  3_bind_text | sq
22230 6c 69 74 65 33 5f 62 69 6e 64 28 53 2c 4e 2c 2e  lite3_bind(S,N,.
22240 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ..)].**         
22250 20 6f 76 65 72 72 69 64 65 20 70 72 69 6f 72 20   override prior 
22260 63 61 6c 6c 73 20 77 69 74 68 20 74 68 65 20 73  calls with the s
22270 61 6d 65 20 76 61 6c 75 65 73 20 6f 66 20 53 20  ame values of S 
22280 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  and N..**.** {H1
22290 33 35 33 30 7d 20 42 69 6e 64 69 6e 67 73 20 65  3530} Bindings e
222a0 73 74 61 62 6c 69 73 68 65 64 20 62 79 20 5b 73  stablished by [s
222b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
222c0 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28   | sqlite3_bind(
222d0 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20 20 20  S,...)].**      
222e0 20 20 20 20 70 65 72 73 69 73 74 20 61 63 72 6f      persist acro
222f0 73 73 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ss calls to [sql
22300 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 0a  ite3_reset(S)]..
22310 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 33 7d 20 49  **.** {H13533} I
22320 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  n calls to [sqli
22330 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c  te3_bind_blob(S,
22340 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20  N,V,L,D)],.**   
22350 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
22360 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c  bind_text(S,N,V,
22370 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20  L,D)], or.**    
22380 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
22390 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56  ind_text16(S,N,V
223a0 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69  ,L,D)] SQLite bi
223b0 6e 64 73 20 74 68 65 20 66 69 72 73 74 20 4c 0a  nds the first L.
223c0 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 74 65  **          byte
223d0 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  s of the BLOB or
223e0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
223f0 74 6f 20 62 79 20 56 2c 20 77 68 65 6e 20 4c 0a  to by V, when L.
22400 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6e  **          is n
22410 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a  on-negative..**.
22420 2a 2a 20 7b 48 31 33 35 33 36 7d 20 49 6e 20 63  ** {H13536} In c
22430 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
22440 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c 56  _bind_text(S,N,V
22450 2c 4c 2c 44 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  ,L,D)] or.**    
22460 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62        [sqlite3_b
22470 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56  ind_text16(S,N,V
22480 2c 4c 2c 44 29 5d 20 53 51 4c 69 74 65 20 62 69  ,L,D)] SQLite bi
22490 6e 64 73 20 63 68 61 72 61 63 74 65 72 73 0a 2a  nds characters.*
224a0 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20  *          from 
224b0 56 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  V through the fi
224c0 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
224d0 65 72 20 77 68 65 6e 20 4c 20 69 73 20 6e 65 67  er when L is neg
224e0 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ative..**.** {H1
224f0 33 35 33 39 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3539} In calls t
22500 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
22510 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  blob(S,N,V,L,D)]
22520 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
22530 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
22540 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72  (S,N,V,L,D)], or
22550 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
22560 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
22570 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68  6(S,N,V,L,D)] wh
22580 65 6e 20 44 20 69 73 20 74 68 65 20 73 70 65 63  en D is the spec
22590 69 61 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ial.**          
225a0 63 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45  constant [SQLITE
225b0 5f 53 54 41 54 49 43 5d 2c 20 53 51 4c 69 74 65  _STATIC], SQLite
225c0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
225d0 65 20 76 61 6c 75 65 20 56 0a 2a 2a 20 20 20 20  e value V.**    
225e0 20 20 20 20 20 20 69 73 20 68 65 6c 64 20 69 6e        is held in
225f0 20 73 74 61 74 69 63 20 75 6e 6d 61 6e 61 67 65   static unmanage
22600 64 20 73 70 61 63 65 20 74 68 61 74 20 77 69 6c  d space that wil
22610 6c 20 6e 6f 74 20 63 68 61 6e 67 65 0a 2a 2a 20  l not change.** 
22620 20 20 20 20 20 20 20 20 20 64 75 72 69 6e 67 20           during 
22630 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 20  the lifetime of 
22640 74 68 65 20 62 69 6e 64 69 6e 67 2e 0a 2a 2a 0a  the binding..**.
22650 2a 2a 20 7b 48 31 33 35 34 32 7d 20 49 6e 20 63  ** {H13542} In c
22660 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
22670 5f 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56  _bind_blob(S,N,V
22680 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,L,D)],.**      
22690 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e      [sqlite3_bin
226a0 64 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44  d_text(S,N,V,L,D
226b0 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
226c0 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
226d0 5f 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c  _text16(S,N,V,L,
226e0 44 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68  D)] when D is th
226f0 65 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20  e special.**    
22700 20 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b        constant [
22710 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
22720 5d 2c 20 74 68 65 20 72 6f 75 74 69 6e 65 20 6d  ], the routine m
22730 61 6b 65 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  akes a.**       
22740 20 20 20 70 72 69 76 61 74 65 20 63 6f 70 79 20     private copy 
22750 6f 66 20 74 68 65 20 76 61 6c 75 65 20 56 20 62  of the value V b
22760 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
22770 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 35 7d  ..**.** {H13545}
22780 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
22790 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
227a0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
227b0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
227c0 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
227d0 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
227e0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
227f0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
22800 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20  ,V,L,D)] when D 
22810 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  is a pointer to.
22820 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 66 75  **          a fu
22830 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 69  nction, SQLite i
22840 6e 76 6f 6b 65 73 20 74 68 61 74 20 66 75 6e 63  nvokes that func
22850 74 69 6f 6e 20 74 6f 20 64 65 73 74 72 6f 79 20  tion to destroy 
22860 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
22870 76 61 6c 75 65 20 56 20 61 66 74 65 72 20 69 74  value V after it
22880 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
22890 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20 56 2e  ing the value V.
228a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 38 7d 20  .**.** {H13548} 
228b0 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  In calls to [sql
228c0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
228d0 6f 62 28 53 2c 4e 2c 56 2c 4c 29 5d 20 74 68 65  ob(S,N,V,L)] the
228e0 20 76 61 6c 75 65 20 62 6f 75 6e 64 0a 2a 2a 20   value bound.** 
228f0 20 20 20 20 20 20 20 20 20 69 73 20 61 20 42 4c           is a BL
22900 4f 42 20 6f 66 20 4c 20 62 79 74 65 73 2c 20 6f  OB of L bytes, o
22910 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
22920 42 4c 4f 42 20 69 66 20 4c 20 69 73 20 6e 65 67  BLOB if L is neg
22930 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ative..**.** {H1
22940 33 35 35 31 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3551} In calls t
22950 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
22960 76 61 6c 75 65 28 53 2c 4e 2c 56 29 5d 20 74 68  value(S,N,V)] th
22970 65 20 56 20 61 72 67 75 6d 65 6e 74 20 6d 61 79  e V argument may
22980 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 65 20  .**          be 
22990 65 69 74 68 65 72 20 61 20 5b 70 72 6f 74 65 63  either a [protec
229a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
229b0 65 5d 20 6f 62 6a 65 63 74 20 6f 72 20 61 6e 0a  e] object or an.
229c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 75 6e 70  **          [unp
229d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
229e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a  _value] object..
229f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
22a00 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
22a10 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
22a20 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
22a30 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
22a40 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
22a50 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
22a60 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
22a70 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
22a80 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
22a90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
22aa0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
22ab0 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
22ac0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
22ad0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
22ae0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
22af0 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
22b00 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
22b10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
22b20 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
22b30 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
22b40 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
22b50 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
22b60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
22b70 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
22b80 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
22b90 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
22ba0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
22bb0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
22bc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
22bd0 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
22be0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
22bf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
22c00 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
22c10 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
22c20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22c30 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
22c40 20 50 61 72 61 6d 65 74 65 72 73 20 7b 48 31 33   Parameters {H13
22c50 36 30 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  600} <S70300>.**
22c60 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
22c70 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
22c80 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
22c90 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
22ca0 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
22cb0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22cc0 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
22cd0 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
22ce0 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
22cf0 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
22d00 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
22d10 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
22d20 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
22d30 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
22d40 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
22d50 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
22d60 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
22d70 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
22d80 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   time..**.** Thi
22d90 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
22da0 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
22db0 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
22dc0 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
22dd0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
22de0 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
22df0 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
22e00 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
22e10 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
22e20 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
22e30 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
22e40 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
22e50 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
22e60 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
22e70 6e 20 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a  n the list..**.*
22e80 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
22e90 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
22ea0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
22eb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
22ec0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
22ed0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
22ee0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
22ef0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
22f00 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
22f10 2a 0a 2a 2a 20 7b 48 31 33 36 30 31 7d 20 54 68  *.** {H13601} Th
22f20 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
22f30 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
22f40 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
22f50 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20  turns.**        
22f60 20 20 74 68 65 20 6c 61 72 67 65 73 74 20 69 6e    the largest in
22f70 64 65 78 20 6f 66 20 61 6c 6c 20 53 51 4c 20 70  dex of all SQL p
22f80 61 72 61 6d 65 74 65 72 73 20 69 6e 20 74 68 65  arameters in the
22f90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
22fa0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22fb0 5d 20 53 2c 20 6f 72 20 30 20 69 66 20 53 20 63  ] S, or 0 if S c
22fc0 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 70  ontains no SQL p
22fd0 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 69 6e  arameters..*/.in
22fe0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
22ff0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
23000 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
23010 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23020 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
23030 61 72 61 6d 65 74 65 72 20 7b 48 31 33 36 32 30  arameter {H13620
23040 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70300>.**.**
23050 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
23060 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
23070 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  to the name of t
23080 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20  he n-th.** [SQL 
23090 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 20  parameter] in a 
230a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
230b0 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72  ent]..** SQL par
230c0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
230d0 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
230e0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
230f0 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
23100 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
23110 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
23120 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
23130 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
23140 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
23150 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
23160 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
23170 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
23180 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
23190 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
231a0 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a   of the name..**
231b0 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   Parameters of t
231c0 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
231d0 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
231e0 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
231f0 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
23200 61 6c 73 6f 20 72 65 66 65 72 72 65 64 20 74 6f  also referred to
23210 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   as "anonymous p
23220 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
23230 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f 73 74  * The first host
23240 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
23250 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
23260 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  t 0..**.** If th
23270 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74  e value n is out
23280 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
23290 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74  the n-th paramet
232a0 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
232b0 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
232c0 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72  returned.  The r
232d0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
232e0 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
232f0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
23300 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
23310 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
23320 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
23330 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
23340 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
23350 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
23360 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
23370 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
23380 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
23390 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
233a0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
233b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
233c0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
233d0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
233e0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
233f0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _index()]..**.**
23400 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
23410 2a 2a 20 7b 48 31 33 36 32 31 7d 20 54 68 65 20  ** {H13621} The 
23420 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
23430 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 53 2c 4e  rameter_name(S,N
23440 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
23450 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
23460 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
23470 6e 67 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 6f  ng of the name o
23480 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
23490 74 65 72 20 69 6e 0a 2a 2a 20 20 20 20 20 20 20  ter in.**       
234a0 20 20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64     the [prepared
234b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
234c0 76 69 6e 67 20 69 6e 64 65 78 20 4e 2c 20 6f 72  ving index N, or
234d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 55 4c  .**          NUL
234e0 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e 6f  L if there is no
234f0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 77   SQL parameter w
23500 69 74 68 20 69 6e 64 65 78 20 4e 20 6f 72 20 69  ith index N or i
23510 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
23520 20 20 70 61 72 61 6d 65 74 65 72 20 77 69 74 68    parameter with
23530 20 69 6e 64 65 78 20 4e 20 69 73 20 61 6e 20 61   index N is an a
23540 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
23550 65 72 20 22 3f 22 2e 0a 2a 2f 0a 63 6f 6e 73 74  er "?"..*/.const
23560 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
23570 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
23580 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
23590 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
235a0 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
235b0 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
235c0 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 20  th A Given Name 
235d0 7b 48 31 33 36 34 30 7d 20 3c 53 37 30 33 30 30  {H13640} <S70300
235e0 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74  >.**.** Return t
235f0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
23600 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
23610 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 54 68  en its name.  Th
23620 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
23630 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
23640 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
23650 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
23660 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
23670 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
23680 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
23690 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65   A zero.** is re
236a0 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
236b0 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
236c0 69 73 20 66 6f 75 6e 64 2e 20 20 54 68 65 20 70  is found.  The p
236d0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
236e0 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
236f0 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
23700 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
23710 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
23720 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
23730 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
23740 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
23750 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
23760 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
23770 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
23780 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
23790 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
237a0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
237b0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
237c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
237d0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  index()]..**.** 
237e0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
237f0 2a 20 7b 48 31 33 36 34 31 7d 20 54 68 65 20 5b  * {H13641} The [
23800 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
23810 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 53 2c 4e  ameter_index(S,N
23820 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
23830 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
23840 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 53 51   the index of SQ
23850 4c 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  L parameter in t
23860 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
23870 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20  tement].**      
23880 20 20 20 20 53 20 77 68 6f 73 65 20 6e 61 6d 65      S whose name
23890 20 6d 61 74 63 68 65 73 20 74 68 65 20 55 54 46   matches the UTF
238a0 2d 38 20 73 74 72 69 6e 67 20 4e 2c 20 6f 72 20  -8 string N, or 
238b0 30 20 69 66 20 74 68 65 72 65 20 69 73 0a 2a 2a  0 if there is.**
238c0 20 20 20 20 20 20 20 20 20 20 6e 6f 20 6d 61 74            no mat
238d0 63 68 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ch..*/.int sqlit
238e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
238f0 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
23900 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
23910 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
23920 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
23930 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
23940 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
23950 74 65 6d 65 6e 74 20 7b 48 31 33 36 36 30 7d 20  tement {H13660} 
23960 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 43  <S70300>.**.** C
23970 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
23980 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
23990 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
239a0 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
239b0 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
239c0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
239d0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
239e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
239f0 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68 69 73 20  t]..** Use this 
23a00 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
23a10 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
23a20 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  ters to NULL..**
23a30 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
23a40 2a 2a 0a 2a 2a 20 7b 48 31 33 36 36 31 7d 20 54  **.** {H13661} T
23a50 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  he [sqlite3_clea
23a60 72 5f 62 69 6e 64 69 6e 67 73 28 53 29 5d 20 69  r_bindings(S)] i
23a70 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
23a80 61 6c 6c 20 53 51 4c 0a 2a 2a 20 20 20 20 20 20  all SQL.**      
23a90 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 62 69      parameter bi
23aa0 6e 64 69 6e 67 73 20 69 6e 20 74 68 65 20 5b 70  ndings in the [p
23ab0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23ac0 74 5d 20 53 20 62 61 63 6b 20 74 6f 20 4e 55 4c  t] S back to NUL
23ad0 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
23ae0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
23af0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
23b00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23b10 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
23b20 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
23b30 53 65 74 20 7b 48 31 33 37 31 30 7d 20 3c 53 31  Set {H13710} <S1
23b40 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75  0700>.**.** Retu
23b50 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
23b60 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
23b70 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
23b80 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
23b90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23ba0 74 5d 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  t]. This routine
23bb0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
23bc0 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a  tmt is an SQL.**
23bd0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
23be0 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
23bf0 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
23c00 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
23c10 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
23c20 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 31 31 7d  :.**.** {H13711}
23c30 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
23c40 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53 29 5d 20 69  lumn_count(S)] i
23c50 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
23c60 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
23c70 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 75 6d  *          colum
23c80 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
23c90 20 73 65 74 20 67 65 6e 65 72 61 74 65 64 20 62   set generated b
23ca0 79 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  y the [prepared 
23cb0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a 2a  statement] S,.**
23cc0 20 20 20 20 20 20 20 20 20 20 6f 72 20 30 20 69            or 0 i
23cd0 66 20 53 20 64 6f 65 73 20 6e 6f 74 20 67 65 6e  f S does not gen
23ce0 65 72 61 74 65 20 61 20 72 65 73 75 6c 74 20 73  erate a result s
23cf0 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  et..*/.int sqlit
23d00 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
23d10 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
23d20 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
23d30 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
23d40 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
23d50 53 65 74 20 7b 48 31 33 37 32 30 7d 20 3c 53 31  Set {H13720} <S1
23d60 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0700>.**.** Thes
23d70 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
23d80 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
23d90 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
23da0 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
23db0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
23dc0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
23dd0 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71  atement.  The sq
23de0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
23df0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
23e00 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
23e10 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
23e20 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
23e30 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
23e40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
23e50 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
23e60 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
23e70 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
23e80 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68  F-16 string.  Th
23e90 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
23ea0 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
23eb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
23ec0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
23ed0 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
23ee0 61 74 65 6d 65 6e 74 2e 20 54 68 65 20 73 65 63  atement. The sec
23ef0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
23f00 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
23f10 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74  umber.  The left
23f20 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
23f30 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54  umber 0..**.** T
23f40 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
23f50 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
23f60 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
23f70 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
23f80 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
23f90 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
23fa0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
23fb0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  ] or until the n
23fc0 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
23fd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
23fe0 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
23ff0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
24000 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
24010 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c  mn..**.** If sql
24020 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
24030 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
24040 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
24050 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
24060 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
24070 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
24080 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
24090 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
240a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
240b0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
240c0 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
240d0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
240e0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
240f0 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
24100 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
24110 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
24120 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
24130 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
24140 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
24150 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
24160 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
24170 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
24180 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
24190 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
241a0 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a  o the next..**.*
241b0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
241c0 0a 2a 2a 20 7b 48 31 33 37 32 31 7d 20 41 20 73  .** {H13721} A s
241d0 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
241e0 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  tion of the [sql
241f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
24200 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20 20  (S,N)].**       
24210 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74     interface ret
24220 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  urns the name of
24230 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
24240 28 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20 20  (where 0 is.**  
24250 20 20 20 20 20 20 20 20 74 68 65 20 6c 65 66 74          the left
24260 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f 72  most column) for
24270 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
24280 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
24290 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
242a0 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20 7a  tement] S as a z
242b0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
242c0 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
242d0 2a 2a 20 7b 48 31 33 37 32 33 7d 20 41 20 73 75  ** {H13723} A su
242e0 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
242f0 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ion of the [sqli
24300 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
24310 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20  6(S,N)].**      
24320 20 20 20 20 69 6e 74 65 72 66 61 63 65 20 72 65      interface re
24330 74 75 72 6e 73 20 74 68 65 20 6e 61 6d 65 20 6f  turns the name o
24340 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
24350 20 28 77 68 65 72 65 20 30 20 69 73 0a 2a 2a 20   (where 0 is.** 
24360 20 20 20 20 20 20 20 20 20 74 68 65 20 6c 65 66           the lef
24370 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 29 20 66 6f  tmost column) fo
24380 72 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  r the result set
24390 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
243a0 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74      [prepared st
243b0 61 74 65 6d 65 6e 74 5d 20 53 20 61 73 20 61 20  atement] S as a 
243c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
243d0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a  UTF-16 string.**
243e0 20 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65            in the
243f0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
24400 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32  er..**.** {H1372
24410 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
24420 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61  column_name()] a
24430 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
24440 6d 6e 5f 6e 61 6d 65 31 36 28 29 5d 0a 2a 2a 20  mn_name16()].** 
24450 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
24460 63 65 73 20 72 65 74 75 72 6e 20 61 20 4e 55 4c  ces return a NUL
24470 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 74 68 65  L pointer if the
24480 79 20 61 72 65 20 75 6e 61 62 6c 65 20 74 6f 0a  y are unable to.
24490 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f  **          allo
244a0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
244b0 6f 6c 64 20 74 68 65 69 72 20 6e 6f 72 6d 61 6c  old their normal
244c0 20 72 65 74 75 72 6e 20 73 74 72 69 6e 67 73 2e   return strings.
244d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 35 7d 20  .**.** {H13725} 
244e0 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  If the N paramet
244f0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
24500 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d  olumn_name(S,N)]
24510 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   or.**          
24520 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
24530 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 73 20  name16(S,N)] is 
24540 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
24550 65 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  en the.**       
24560 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 72 65     interfaces re
24570 74 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  turn a NULL poin
24580 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  ter..**.** {H137
24590 32 36 7d 20 54 68 65 20 73 74 72 69 6e 67 73 20  26} The strings 
245a0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
245b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
245c0 28 53 2c 4e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20  (S,N)] and.**   
245d0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
245e0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c  column_name16(S,
245f0 4e 29 5d 20 61 72 65 20 76 61 6c 69 64 20 75 6e  N)] are valid un
24600 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20  til the next.** 
24610 20 20 20 20 20 20 20 20 20 63 61 6c 6c 20 74 6f           call to
24620 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 20   either routine 
24630 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 53 20  with the same S 
24640 61 6e 64 20 4e 20 70 61 72 61 6d 65 74 65 72 73  and N parameters
24650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
24660 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 66  until [sqlite3_f
24670 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63  inalize(S)] is c
24680 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  alled..**.** {H1
24690 33 37 32 37 7d 20 57 68 65 6e 20 61 20 72 65 73  3727} When a res
246a0 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20  ult column of a 
246b0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
246c0 6e 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20  nt contains.**  
246d0 20 20 20 20 20 20 20 20 61 6e 20 41 53 20 63 6c          an AS cl
246e0 61 75 73 65 2c 20 74 68 65 20 6e 61 6d 65 20 6f  ause, the name o
246f0 66 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  f that column is
24700 20 74 68 65 20 69 64 65 6e 74 69 66 69 65 72 0a   the identifier.
24710 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 74  **          to t
24720 68 65 20 72 69 67 68 74 20 6f 66 20 74 68 65 20  he right of the 
24730 41 53 20 6b 65 79 77 6f 72 64 2e 0a 2a 2f 0a 63  AS keyword..*/.c
24740 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
24750 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
24760 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24770 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
24780 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
24790 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
247a0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
247b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
247c0 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
247d0 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
247e0 20 7b 48 31 33 37 34 30 7d 20 3c 53 31 30 37 30   {H13740} <S1070
247f0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  0>.**.** These r
24800 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
24810 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
24820 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e  mine what column
24830 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c   of what.** tabl
24840 65 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62  e in which datab
24850 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20  ase a result of 
24860 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
24870 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e  ment comes from.
24880 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
24890 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
248a0 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
248b0 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
248c0 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
248d0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
248e0 74 72 69 6e 67 2e 20 20 54 68 65 20 5f 64 61 74  tring.  The _dat
248f0 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
24900 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
24910 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
24920 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
24930 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
24940 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
24950 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
24960 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
24970 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
24980 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
24990 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
249a0 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
249b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
249c0 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
249d0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
249e0 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
249f0 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
24a00 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
24a10 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
24a20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
24a30 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  ng..**.** The na
24a40 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
24a50 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
24a60 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
24a70 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
24a80 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
24a90 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lumn..**.** The 
24aa0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
24ab0 6f 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  o the following 
24ac0 63 61 6c 6c 73 20 69 73 20 61 20 5b 70 72 65 70  calls is a [prep
24ad0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
24ae0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
24af0 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
24b00 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
24b10 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
24b20 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
24b30 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
24b40 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
24b50 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
24b60 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  t..**.** If the 
24b70 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
24b80 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
24b90 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
24ba0 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
24bb0 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
24bc0 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
24bd0 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
24be0 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
24bf0 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65  rn.** NULL.  The
24c00 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
24c10 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
24c20 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
24c30 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
24c40 2a 20 6f 63 63 75 72 73 2e 20 20 4f 74 68 65 72  * occurs.  Other
24c50 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
24c60 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
24c70 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
24c80 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e  ase, table.** an
24c90 64 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  d column that qu
24ca0 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
24cb0 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
24cc0 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77  from..**.** As w
24cd0 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
24ce0 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
24cf0 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68 20   postfixed with 
24d00 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
24d10 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
24d20 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65 72  rings, the other
24d30 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
24d40 6e 20 55 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a  n UTF-8. {END}.*
24d50 2a 0a 2a 2a 20 54 68 65 73 65 20 41 50 49 73 20  *.** These APIs 
24d60 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
24d70 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
24d80 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
24d90 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
24da0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
24db0 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
24dc0 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
24dd0 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
24de0 7b 41 31 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74  {A13751}.** If t
24df0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
24e00 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
24e10 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
24e20 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
24e30 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
24e40 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
24e50 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
24e60 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
24e70 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
24e80 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
24e90 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
24ea0 0a 2a 2a 20 7b 48 31 33 37 34 31 7d 20 54 68 65  .** {H13741} The
24eb0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
24ec0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 53  _database_name(S
24ed0 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
24ee0 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
24ef0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
24f00 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
24f10 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
24f20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 77 68  database from wh
24f30 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ich the.**      
24f40 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63      Nth result c
24f50 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72  olumn of the [pr
24f60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24f70 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64  ] S is extracted
24f80 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
24f90 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
24fa0 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
24fb0 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73  a general expres
24fc0 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  sion.**         
24fd0 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
24fe0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
24ff0 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61   to store the na
25000 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34  me..**.** {H1374
25010 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
25020 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
25030 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74  name16(S,N)] int
25040 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 65  erface returns e
25050 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
25060 20 20 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74    the UTF-16 nat
25070 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 7a  ive byte order z
25080 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e  ero-terminated n
25090 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
250a0 61 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ase.**          
250b0 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e  from which the N
250c0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
250d0 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
250e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
250f0 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78  s.**          ex
25100 74 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c  tracted, or NULL
25110 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
25120 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e  mn of S is a gen
25130 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a  eral expression.
25140 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
25150 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
25160 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73  cate memory to s
25170 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
25180 2a 0a 2a 2a 20 7b 48 31 33 37 34 33 7d 20 54 68  *.** {H13743} Th
25190 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
251a0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 53 2c 4e  n_table_name(S,N
251b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
251c0 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
251d0 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
251e0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
251f0 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 74 61  d name of the ta
25200 62 6c 65 20 66 72 6f 6d 20 77 68 69 63 68 20 74  ble from which t
25210 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e  he.**          N
25220 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
25230 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61 72 65   of the [prepare
25240 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
25250 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20  s extracted,.** 
25260 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c           or NULL
25270 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75   if the Nth colu
25280 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67 65 6e  mn of S is a gen
25290 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a  eral expression.
252a0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  **          or i
252b0 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  f unable to allo
252c0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73  cate memory to s
252d0 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a  tore the name..*
252e0 2a 0a 2a 2a 20 7b 48 31 33 37 34 34 7d 20 54 68  *.** {H13744} Th
252f0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
25300 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 53  n_table_name16(S
25310 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  ,N)] interface r
25320 65 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a  eturns either.**
25330 20 20 20 20 20 20 20 20 20 20 74 68 65 20 55 54            the UT
25340 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
25350 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d   order zero-term
25360 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
25370 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20  he table.**     
25380 20 20 20 20 20 66 72 6f 6d 20 77 68 69 63 68 20       from which 
25390 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
253a0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72  olumn of the [pr
253b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
253c0 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ] S is.**       
253d0 20 20 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72     extracted, or
253e0 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
253f0 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
25400 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73  a general expres
25410 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  sion.**         
25420 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
25430 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
25440 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61   to store the na
25450 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34  me..**.** {H1374
25460 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
25470 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
25480 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  me(S,N)] interfa
25490 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
254a0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  r.**          th
254b0 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  e UTF-8 zero-ter
254c0 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20  minated name of 
254d0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
254e0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 0a   from which the.
254f0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
25500 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66  result column of
25510 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
25520 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65  tatement] S is e
25530 78 74 72 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20  xtracted,.**    
25540 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66        or NULL if
25550 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
25560 6f 66 20 53 20 69 73 20 61 20 67 65 6e 65 72 61  of S is a genera
25570 6c 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  l expression.** 
25580 20 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 75           or if u
25590 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
255a0 65 20 6d 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72  e memory to stor
255b0 65 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a  e the name..**.*
255c0 2a 20 7b 48 31 33 37 34 36 7d 20 54 68 65 20 5b  * {H13746} The [
255d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
255e0 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e  rigin_name16(S,N
255f0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
25600 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20  urns either.**  
25610 20 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d          the UTF-
25620 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
25630 72 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  rder zero-termin
25640 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65  ated name of the
25650 20 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20   table.**       
25660 20 20 20 63 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77     column from w
25670 68 69 63 68 20 74 68 65 20 4e 74 68 20 72 65 73  hich the Nth res
25680 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ult column of th
25690 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
256a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
256b0 74 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65  t] S is extracte
256c0 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
256d0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  e Nth column.** 
256e0 20 20 20 20 20 20 20 20 20 6f 66 20 53 20 69 73           of S is
256f0 20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65   a general expre
25700 73 73 69 6f 6e 20 6f 72 20 69 66 20 75 6e 61 62  ssion or if unab
25710 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
25720 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20  emory.**        
25730 20 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e    to store the n
25740 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37  ame..**.** {H137
25750 34 38 7d 20 54 68 65 20 72 65 74 75 72 6e 20 76  48} The return v
25760 61 6c 75 65 73 20 66 72 6f 6d 0a 2a 2a 20 20 20  alues from.**   
25770 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
25780 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
25790 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
257a0 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
257b0 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  s].**          a
257c0 72 65 20 76 61 6c 69 64 20 66 6f 72 20 74 68 65  re valid for the
257d0 20 6c 69 66 65 74 69 6d 65 20 6f 66 20 74 68 65   lifetime of the
257e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
257f0 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20  ment].**        
25800 20 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 65    or until the e
25810 6e 63 6f 64 69 6e 67 20 69 73 20 63 68 61 6e 67  ncoding is chang
25820 65 64 20 62 79 20 61 6e 6f 74 68 65 72 20 6d 65  ed by another me
25830 74 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20  tadata.**       
25840 20 20 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c     interface cal
25850 6c 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 70  l for the same p
25860 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25870 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  t and column..**
25880 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
25890 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 20  .**.** {A13751} 
258a0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
258b0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
258c0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 20 20 20 20 20  or more.**      
258d0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c      [sqlite3_col
258e0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
258f0 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
25900 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
25910 2a 2a 20 20 20 20 20 20 20 20 20 20 66 6f 72 20  **          for 
25920 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
25930 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
25940 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
25950 2a 2a 20 20 20 20 20 20 20 20 20 20 61 74 20 74  **          at t
25960 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
25970 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
25980 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
25990 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
259a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
259b0 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
259c0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
259d0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
259e0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
259f0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
25a00 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
25a10 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
25a20 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
25a30 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
25a40 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
25a50 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
25a60 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
25a70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
25a80 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
25a90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
25aa0 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
25ab0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
25ac0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
25ad0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
25ae0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
25af0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
25b00 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
25b10 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
25b20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b  A Query Result {
25b30 48 31 33 37 36 30 7d 20 3c 53 31 30 37 30 30 3e  H13760} <S10700>
25b40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
25b50 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
25b60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25b70 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
25b80 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
25b90 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
25ba0 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
25bb0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
25bc0 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
25bd0 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
25be0 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
25bf0 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
25c00 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
25c10 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
25c20 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
25c30 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
25c40 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
25c50 6e 65 64 2e 20 20 49 66 20 74 68 65 20 4e 74 68  ned.  If the Nth
25c60 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
25c70 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
25c80 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
25c90 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
25ca0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
25cb0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 54  s returned..** T
25cc0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
25cd0 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
25ce0 2d 38 20 65 6e 63 6f 64 65 64 2e 20 7b 45 4e 44  -8 encoded. {END
25cf0 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  }.**.** For exam
25d00 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
25d10 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
25d20 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
25d30 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
25d40 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
25d50 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
25d60 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
25d70 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
25d80 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
25d90 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
25da0 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
25db0 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
25dc0 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
25dd0 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
25de0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
25df0 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
25e00 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
25e10 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
25e20 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20  n (i==0)..**.** 
25e30 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
25e40 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
25e50 69 6e 67 2e 20 20 53 6f 20 6a 75 73 74 20 62 65  ing.  So just be
25e60 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a  cause a column.*
25e70 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f  * is declared to
25e80 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69   contain a parti
25e90 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20  cular type does 
25ea0 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68  not mean that th
25eb0 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64  e.** data stored
25ec0 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   in that column 
25ed0 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72  is of the declar
25ee0 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65  ed type.  SQLite
25ef0 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20   is.** strongly 
25f00 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74  typed, but the t
25f10 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63  yping is dynamic
25f20 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 54 79   not static.  Ty
25f30 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
25f40 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
25f50 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
25f60 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
25f70 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
25f80 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
25f90 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
25fa0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36  TS:.**.** {H1376
25fb0 31 7d 20 20 41 20 73 75 63 63 65 73 73 66 75 6c  1}  A successful
25fc0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
25fd0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
25fe0 65 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20  e(S,N)] returns 
25ff0 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 7a  a.**           z
26000 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
26010 54 46 2d 38 20 73 74 72 69 6e 67 20 63 6f 6e 74  TF-8 string cont
26020 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61  aining the decla
26030 72 65 64 20 64 61 74 61 74 79 70 65 0a 2a 2a 20  red datatype.** 
26040 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
26050 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
26060 61 74 20 61 70 70 65 61 72 73 20 61 73 20 74 68  at appears as th
26070 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75  e Nth column (nu
26080 6d 62 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20  mbered.**       
26090 20 20 20 20 66 72 6f 6d 20 30 29 20 6f 66 20 74      from 0) of t
260a0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f  he result set to
260b0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
260c0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
260d0 2a 2a 20 7b 48 31 33 37 36 32 7d 20 20 41 20 73  ** {H13762}  A s
260e0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
260f0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  o [sqlite3_colum
26100 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 53 2c 4e  n_decltype16(S,N
26110 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  )].**           
26120 72 65 74 75 72 6e 73 20 61 20 7a 65 72 6f 2d 74  returns a zero-t
26130 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36  erminated UTF-16
26140 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
26150 65 72 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20  er string.**    
26160 20 20 20 20 20 20 20 63 6f 6e 74 61 69 6e 69 6e         containin
26170 67 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 64  g the declared d
26180 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 74  atatype of the t
26190 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
261a0 20 61 70 70 65 61 72 73 0a 2a 2a 20 20 20 20 20   appears.**     
261b0 20 20 20 20 20 20 61 73 20 74 68 65 20 4e 74 68        as the Nth
261c0 20 63 6f 6c 75 6d 6e 20 28 6e 75 6d 62 65 72 65   column (numbere
261d0 64 20 66 72 6f 6d 20 30 29 20 6f 66 20 74 68 65  d from 0) of the
261e0 20 72 65 73 75 6c 74 20 73 65 74 20 74 6f 20 74   result set to t
261f0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  he.**           
26200 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26210 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ent] S..**.** {H
26220 31 33 37 36 33 7d 20 20 49 66 20 4e 20 69 73 20  13763}  If N is 
26230 6c 65 73 73 20 74 68 61 6e 20 30 20 6f 72 20 4e  less than 0 or N
26240 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
26250 20 6f 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20   or equal to.** 
26260 20 20 20 20 20 20 20 20 20 20 74 68 65 20 6e 75            the nu
26270 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
26280 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
26290 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2c 0a 2a   statement] S,.*
262a0 2a 20 20 20 20 20 20 20 20 20 20 20 6f 72 20 69  *           or i
262b0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
262c0 20 6f 66 20 53 20 69 73 20 61 6e 20 65 78 70 72   of S is an expr
262d0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
262e0 72 79 20 72 61 74 68 65 72 0a 2a 2a 20 20 20 20  ry rather.**    
262f0 20 20 20 20 20 20 20 74 68 61 6e 20 61 20 74 61         than a ta
26300 62 6c 65 20 63 6f 6c 75 6d 6e 2c 20 6f 72 20 69  ble column, or i
26310 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
26320 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 0a 2a 2a  ation failure.**
26330 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72             occur
26340 73 20 64 75 72 69 6e 67 20 65 6e 63 6f 64 69 6e  s during encodin
26350 67 20 63 6f 6e 76 65 72 73 69 6f 6e 73 2c 20 74  g conversions, t
26360 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
26370 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
26380 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
26390 70 65 28 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20  pe(S,N)] or.**  
263a0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
263b0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
263c0 65 31 36 28 53 2c 4e 29 5d 20 72 65 74 75 72 6e  e16(S,N)] return
263d0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63 6f 6e 73 74 20   NULL..*/.const 
263e0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
263f0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
26400 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
26410 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
26420 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
26430 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
26440 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
26450 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
26460 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
26470 74 65 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d 20  tement {H13200} 
26480 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 41  <S10000>.**.** A
26490 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64  fter a [prepared
264a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
264b0 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73  been prepared us
264c0 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73  ing either.** [s
264d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
264e0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
264f0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
26500 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c   or one of the l
26510 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
26520 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
26530 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  pare()] or [sqli
26540 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
26550 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  , this function.
26560 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ** must be calle
26570 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
26580 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20  mes to evaluate 
26590 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  the statement..*
265a0 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
265b0 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72   of the behavior
265c0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
265d0 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65  step() interface
265e0 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68   depend.** on wh
265f0 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d  ether the statem
26600 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64  ent was prepared
26610 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72   using the newer
26620 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a   "v2" interface.
26630 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
26640 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
26650 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
26660 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c  _v2()] or the ol
26670 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  der legacy.** in
26680 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33  terface [sqlite3
26690 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
266a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
266b0 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20  16()].  The use 
266c0 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76  of the.** new "v
266d0 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
266e0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
266f0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
26700 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a   but the legacy.
26710 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  ** interface wil
26720 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  l continue to be
26730 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a   supported..**.*
26740 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  * In the legacy 
26750 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
26760 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
26770 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
26780 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
26790 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
267a0 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
267b0 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
267c0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
267d0 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69   With the "v2" i
267e0 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
267f0 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
26800 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
26810 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
26820 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
26830 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
26840 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  l..**.** [SQLITE
26850 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
26860 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
26870 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
26880 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
26890 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
268a0 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
268b0 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74 68   its job.  If th
268c0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
268d0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
268e0 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
268f0 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
26900 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
26910 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
26920 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
26930 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
26940 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
26950 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
26960 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69  ithin a.** expli
26970 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
26980 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
26990 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
269a0 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
269b0 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
269c0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  *.** [SQLITE_DON
269d0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
269e0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
269f0 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
26a00 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
26a10 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
26a20 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
26a30 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
26a40 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
26a50 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
26a60 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
26a70 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
26a80 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
26a90 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
26aa0 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
26ab0 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
26ac0 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
26ad0 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
26ae0 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
26af0 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
26b00 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
26b10 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
26b20 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
26b30 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
26b40 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
26b50 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
26b60 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
26b70 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
26b80 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
26b90 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
26ba0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
26bb0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
26bc0 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
26bd0 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
26be0 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ta..**.** [SQLIT
26bf0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
26c00 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
26c10 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
26c20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
26c30 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
26c40 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
26c50 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
26c60 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
26c70 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
26c80 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
26c90 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
26ca0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
26cb0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
26cc0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
26cd0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
26ce0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
26cf0 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
26d00 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
26d10 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
26d20 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
26d30 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
26d40 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
26d50 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
26d60 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
26d70 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
26d80 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
26d90 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e 20  statement].  In 
26da0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
26db0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
26dc0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
26dd0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
26de0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
26df0 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
26e00 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
26e10 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
26e20 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
26e30 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
26e40 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
26e50 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
26e60 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
26e70 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
26e80 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
26e90 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
26ea0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
26eb0 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
26ec0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
26ed0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
26ee0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
26ef0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
26f00 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
26f10 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
26f20 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
26f30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
26f40 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
26f50 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
26f60 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
26f70 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
26f80 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79  ..**.** <b>Goofy
26f90 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
26fa0 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67  :</b> In the leg
26fb0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
26fc0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
26fd0 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20  ).** API always 
26fe0 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
26ff0 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53  c error code, [S
27000 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f  QLITE_ERROR], fo
27010 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65  llowing any.** e
27020 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
27030 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e  [SQLITE_BUSY] an
27040 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  d [SQLITE_MISUSE
27050 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c  ].  You must cal
27060 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  l.** [sqlite3_re
27070 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
27080 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
27090 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
270a0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70  one of the.** sp
270b0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
270c0 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72  des] that better
270d0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
270e0 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69  rror..** We admi
270f0 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61  t that this is a
27100 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20   goofy design.  
27110 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20  The problem has 
27120 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69  been fixed.** wi
27130 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
27140 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70  rface.  If you p
27150 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f  repare all of yo
27160 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ur SQL statement
27170 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65  s.** using eithe
27180 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
27190 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
271a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
271b0 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  2()] instead.** 
271c0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
271d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
271e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
271f0 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
27200 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
27210 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
27220 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
27230 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
27240 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
27250 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
27260 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
27270 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
27280 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
27290 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
272a0 2a 2a 20 7b 48 31 33 32 30 32 7d 20 20 49 66 20  ** {H13202}  If 
272b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
272c0 61 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 72 65  atement] S is re
272d0 61 64 79 20 74 6f 20 62 65 20 72 75 6e 2c 20 74  ady to be run, t
272e0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
272f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
27300 29 5d 20 61 64 76 61 6e 63 65 73 20 74 68 61 74  )] advances that
27310 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
27320 65 6e 74 20 75 6e 74 69 6c 0a 2a 2a 20 20 20 20  ent until.**    
27330 20 20 20 20 20 20 20 63 6f 6d 70 6c 65 74 69 6f         completio
27340 6e 20 6f 72 20 75 6e 74 69 6c 20 69 74 20 69 73  n or until it is
27350 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e   ready to return
27360 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f 66 20   another row of 
27370 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
27380 20 72 65 73 75 6c 74 20 73 65 74 2c 20 6f 72 20   result set, or 
27390 75 6e 74 69 6c 20 61 6e 20 5b 73 71 6c 69 74 65  until an [sqlite
273a0 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e  3_interrupt | in
273b0 74 65 72 72 75 70 74 5d 0a 2a 2a 20 20 20 20 20  terrupt].**     
273c0 20 20 20 20 20 20 6f 72 20 61 20 72 75 6e 2d 74        or a run-t
273d0 69 6d 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ime error occurs
273e0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 34 7d  ..**.** {H15304}
273f0 20 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f    When a call to
27400 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
27410 29 5d 20 63 61 75 73 65 73 20 74 68 65 20 5b 70  )] causes the [p
27420 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27430 74 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  t].**           
27440 53 20 74 6f 20 72 75 6e 20 74 6f 20 63 6f 6d 70  S to run to comp
27450 6c 65 74 69 6f 6e 2c 20 74 68 65 20 66 75 6e 63  letion, the func
27460 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51  tion returns [SQ
27470 4c 49 54 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a  LITE_DONE]..**.*
27480 2a 20 7b 48 31 35 33 30 36 7d 20 20 57 68 65 6e  * {H15306}  When
27490 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
274a0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 73 74 6f  te3_step(S)] sto
274b0 70 73 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ps because it is
274c0 20 72 65 61 64 79 20 74 6f 0a 2a 2a 20 20 20 20   ready to.**    
274d0 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 61 6e         return an
274e0 6f 74 68 65 72 20 72 6f 77 20 6f 66 20 74 68 65  other row of the
274f0 20 72 65 73 75 6c 74 20 73 65 74 2c 20 69 74 20   result set, it 
27500 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
27510 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ROW]..**.** {H15
27520 33 30 38 7d 20 20 49 66 20 61 20 63 61 6c 6c 20  308}  If a call 
27530 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
27540 28 53 29 5d 20 65 6e 63 6f 75 6e 74 65 72 73 20  (S)] encounters 
27550 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  an.**           
27560 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
27570 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 20  pt | interrupt] 
27580 6f 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  or a run-time er
27590 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ror,.**         
275a0 20 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20    it returns an 
275b0 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
275c0 72 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 6e  r code that is n
275d0 6f 74 20 6f 6e 65 20 6f 66 0a 2a 2a 20 20 20 20  ot one of.**    
275e0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f         [SQLITE_O
275f0 4b 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  K], [SQLITE_ROW]
27600 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  , or [SQLITE_DON
27610 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 31  E]..**.** {H1531
27620 30 7d 20 20 49 66 20 61 6e 20 5b 73 71 6c 69 74  0}  If an [sqlit
27630 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69  e3_interrupt | i
27640 6e 74 65 72 72 75 70 74 5d 20 6f 72 20 61 20 72  nterrupt] or a r
27650 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 0a 2a 2a  un-time error.**
27660 20 20 20 20 20 20 20 20 20 20 20 6f 63 63 75 72             occur
27670 73 20 64 75 72 69 6e 67 20 61 20 63 61 6c 6c 20  s during a call 
27680 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
27690 28 53 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  (S)].**         
276a0 20 20 66 6f 72 20 61 20 5b 70 72 65 70 61 72 65    for a [prepare
276b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 63  d statement] S c
276c0 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20  reated using.** 
276d0 20 20 20 20 20 20 20 20 20 20 6c 65 67 61 63 79            legacy
276e0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
276f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
27700 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
27710 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
27720 31 36 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  16()], then the 
27730 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
27740 20 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20   either.**      
27750 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
27760 4f 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  OR], [SQLITE_BUS
27770 59 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  Y], or [SQLITE_M
27780 49 53 55 53 45 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ISUSE]..*/.int s
27790 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
277a0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
277b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
277c0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
277d0 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b  n a result set {
277e0 48 31 33 37 37 30 7d 20 3c 53 31 30 37 30 30 3e  H13770} <S10700>
277f0 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74  .**.** Returns t
27800 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c  he number of val
27810 75 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65  ues in the curre
27820 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
27830 73 75 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  sult set..**.** 
27840 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
27850 2a 20 7b 48 31 33 37 37 31 7d 20 20 41 66 74 65  * {H13771}  Afte
27860 72 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  r a call to [sql
27870 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 74 68  ite3_step(S)] th
27880 61 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  at returns [SQLI
27890 54 45 5f 52 4f 57 5d 2c 0a 2a 2a 20 20 20 20 20  TE_ROW],.**     
278a0 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74        the [sqlit
278b0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 53 29  e3_data_count(S)
278c0 5d 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72  ] routine will r
278d0 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 76  eturn the same v
278e0 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  alue.**         
278f0 20 20 61 73 20 74 68 65 20 5b 73 71 6c 69 74 65    as the [sqlite
27900 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 53  3_column_count(S
27910 29 5d 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  )] function..**.
27920 2a 2a 20 7b 48 31 33 37 37 32 7d 20 20 41 66 74  ** {H13772}  Aft
27930 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
27940 28 53 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  (S)] has returne
27950 64 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  d any value othe
27960 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 20  r than.**       
27970 20 20 20 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d      [SQLITE_ROW]
27980 20 6f 72 20 62 65 66 6f 72 65 20 5b 73 71 6c 69   or before [sqli
27990 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
279a0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
279b0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
279c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
279d0 6d 65 6e 74 5d 20 66 6f 72 20 74 68 65 20 66 69  ment] for the fi
279e0 72 73 74 20 74 69 6d 65 20 73 69 6e 63 65 20 69  rst time since i
279f0 74 20 77 61 73 0a 2a 2a 20 20 20 20 20 20 20 20  t was.**        
27a00 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70     [sqlite3_prep
27a10 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
27a20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
27a30 74 20 7c 20 72 65 73 65 74 5d 2c 0a 2a 2a 20 20  t | reset],.**  
27a40 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 73 71           the [sq
27a50 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
27a60 28 53 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  (S)] routine ret
27a70 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2f 0a 69 6e  urns zero..*/.in
27a80 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  t sqlite3_data_c
27a90 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
27aa0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
27ab0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64  * CAPI3REF: Fund
27ac0 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65  amental Datatype
27ad0 73 20 7b 48 31 30 32 36 35 7d 20 3c 53 31 30 31  s {H10265} <S101
27ae0 31 30 3e 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b  10><S10120>.** K
27af0 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
27b00 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32  TEXT.**.** {H102
27b10 36 36 7d 20 45 76 65 72 79 20 76 61 6c 75 65 20  66} Every value 
27b20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
27b30 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
27b40 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
27b50 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
27b60 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
27b70 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
27b80 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
27b90 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
27ba0 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
27bb0 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
27bc0 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
27bd0 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  </ul> {END}.**.*
27be0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
27bf0 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
27c00 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
27c10 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
27c20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
27c30 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
27c40 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
27c50 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
27c60 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
27c70 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
27c80 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
27c90 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
27ca0 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
27cb0 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
27cc0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
27cd0 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
27ce0 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
27cf0 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
27d00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
27d10 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
27d20 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
27d30 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
27d40 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
27d50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
27d60 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
27d70 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
27d80 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
27d90 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
27da0 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
27db0 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
27dc0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
27dd0 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
27de0 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
27df0 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 20  es From A Query 
27e00 7b 48 31 33 38 30 30 7d 20 3c 53 31 30 37 30 30  {H13800} <S10700
27e10 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
27e20 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
27e30 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
27e40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
27e50 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73  rm the "result s
27e60 65 74 20 71 75 65 72 79 22 20 69 6e 74 65 72 66  et query" interf
27e70 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ace..**.** These
27e80 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
27e90 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
27ea0 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
27eb0 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
27ec0 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
27ed0 6f 66 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20  of a query.  In 
27ee0 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
27ef0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
27f00 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
27f10 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
27f20 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
27f30 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
27f40 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
27f50 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
27f60 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
27f70 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
27f80 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
27f90 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
27fa0 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
27fb0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
27fc0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
27fd0 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
27fe0 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
27ff0 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
28000 64 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74  d.  The leftmost
28010 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
28020 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
28030 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a  e index 0..**.**
28040 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
28050 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
28060 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
28070 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
28080 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
28090 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
280a0 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
280b0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
280c0 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
280d0 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
280e0 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
280f0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
28100 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
28110 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
28120 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
28130 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
28140 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
28150 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
28160 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
28170 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
28180 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
28190 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
281a0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
281b0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
281c0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
281d0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
281e0 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
281f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
28200 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
28210 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
28220 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
28230 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
28240 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
28250 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
28260 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
28270 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
28280 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
28290 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
282a0 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
282b0 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
282c0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
282d0 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
282e0 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
282f0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
28300 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
28310 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
28320 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
28330 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
28340 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
28350 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
28360 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
28370 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
28380 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
28390 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
283a0 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
283b0 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
283c0 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
283d0 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
283e0 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
283f0 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
28400 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
28410 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
28420 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
28430 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
28440 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
28450 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
28460 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
28470 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
28480 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
28490 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
284a0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
284b0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
284c0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
284d0 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
284e0 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
284f0 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
28500 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
28510 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28520 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
28530 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
28540 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rsion..**.** If 
28550 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
28560 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
28570 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
28580 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
28590 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
285a0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
285b0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
285c0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
285d0 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65  ng..** If the re
285e0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
285f0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
28600 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
28610 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
28620 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
28630 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
28640 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
28650 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66   of bytes..** If
28660 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
28670 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
28680 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
28690 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
286a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
286b0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
286c0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
286d0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
286e0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
286f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
28700 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
28710 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  g..** The value 
28720 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
28730 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
28740 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74  ro terminator at
28750 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
28760 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20  he string.  For 
28770 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
28780 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74  ue returned is t
28790 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
287a0 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
287b0 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
287c0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
287d0 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73  s..**.** Strings
287e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
287f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
28800 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
28810 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
28820 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
28830 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
28840 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65  s zero terminate
28850 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a 2a  d.  The return.*
28860 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
28870 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
28880 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
28890 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20  ngth BLOB is an 
288a0 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69  arbitrary.** poi
288b0 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65  nter, possibly e
288c0 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ven a NULL point
288d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
288e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
288f0 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69  es16() routine i
28900 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c  s similar to sql
28910 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
28920 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65  s().** but leave
28930 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20  s the result in 
28940 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
28950 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74   byte order inst
28960 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a  ead of UTF-8..**
28970 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   The zero termin
28980 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c  ator is not incl
28990 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75  uded in this cou
289a0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62  nt..**.** The ob
289b0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
289c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
289d0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
289e0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
289f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
28a00 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f  bject.  An unpro
28a10 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
28a20 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d  alue object.** m
28a30 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
28a40 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69  with [sqlite3_bi
28a50 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
28a60 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
28a70 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
28a80 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
28a90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
28aa0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
28ab0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
28ac0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
28ad0 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
28ae0 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
28af0 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
28b00 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
28b10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
28b20 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
28b30 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
28b40 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
28b50 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20  _bytes()], then 
28b60 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
28b70 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
28b80 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
28b90 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
28ba0 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
28bb0 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
28bc0 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
28bd0 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
28be0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
28bf0 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
28c00 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
28c10 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
28c20 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
28c30 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
28c40 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
28c50 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
28c60 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
28c70 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
28c80 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
28c90 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
28ca0 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
28cb0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
28cc0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
28cd0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
28ce0 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
28cf0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
28d00 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
28d10 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
28d20 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
28d30 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
28d40 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
28d50 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
28d60 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
28d70 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
28d80 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
28d90 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
28da0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
28db0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
28dc0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
28dd0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
28de0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
28df0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
28e00 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
28e10 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
28e20 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
28e30 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
28e40 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
28e50 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
28e60 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
28e70 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
28e80 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
28e90 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
28ea0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
28eb0 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
28ec0 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
28ed0 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
28ee0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
28ef0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
28f00 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
28f10 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65  om float to inte
28f20 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
28f30 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
28f40 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
28f50 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
28f60 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
28f70 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
28f80 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
28f90 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54  d> Same as FLOAT
28fa0 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
28fb0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
28fc0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
28fd0 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  Use atoi().** <t
28fe0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
28ff0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
29000 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a  td> Use atof().*
29010 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
29020 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
29030 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
29040 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
29050 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
29060 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
29070 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
29080 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  use atoi().** <t
29090 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
290a0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
290b0 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
290c0 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
290d0 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
290e0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
290f0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
29100 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
29110 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
29120 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
29130 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
29140 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
29150 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
29160 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
29170 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
29180 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
29190 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
291a0 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
291b0 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
291c0 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
291d0 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74  * own equivalent
291e0 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
291f0 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
29200 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
29210 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
29220 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
29230 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
29240 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
29250 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
29260 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
29270 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
29280 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
29290 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
292a0 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
292b0 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
292c0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
292d0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
292e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
292f0 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
29300 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
29310 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
29320 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
29330 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
29340 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
29350 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
29360 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
29370 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
29380 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
29390 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
293a0 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
293b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
293c0 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
293d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
293e0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
293f0 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
29400 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
29410 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
29420 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
29430 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
29440 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
29450 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
29460 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
29470 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
29480 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
29490 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
294a0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
294b0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
294c0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
294d0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
294e0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
294f0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
29500 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
29510 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
29520 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
29530 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
29540 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
29550 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
29560 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
29570 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
29580 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
29590 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e   </ul>.**.** Con
295a0 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
295b0 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
295c0 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
295d0 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
295e0 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
295f0 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
29600 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
29610 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
29620 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
29630 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
29640 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70   prior pointer p
29650 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61  oints to will ha
29660 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
29670 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
29680 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
29690 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
296a0 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
296b0 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
296c0 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
296d0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
296e0 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
296f0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
29700 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
29710 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
29720 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
29730 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
29740 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
29750 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
29760 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
29770 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
29780 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
29790 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
297a0 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
297b0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
297c0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
297d0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
297e0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
297f0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
29800 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
29810 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
29820 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
29830 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
29840 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29850 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
29860 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
29870 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
29880 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
29890 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
298a0 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
298b0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
298c0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
298d0 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
298e0 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
298f0 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
29900 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
29910 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
29920 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
29930 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
29940 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
29950 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
29960 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
29970 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
29980 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
29990 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
299a0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
299b0 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
299c0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
299d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
299e0 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
299f0 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
29a00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
29a10 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
29a20 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
29a30 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
29a40 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20  ** The pointers 
29a50 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
29a60 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
29a70 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
29a80 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
29a90 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
29aa0 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
29ab0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
29ac0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
29ad0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
29ae0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  )] is called.  T
29af0 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
29b00 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
29b10 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42  ings.** and BLOB
29b20 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
29b30 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62  atically.  Do <b
29b40 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68  >not</b> pass th
29b50 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
29b60 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ned.** [sqlite3_
29b70 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
29b80 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
29b90 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
29ba0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
29bb0 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ree()]..**.** If
29bc0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
29bd0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
29be0 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
29bf0 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
29c00 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
29c10 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
29c20 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
29c30 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
29c40 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
29c50 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
29c60 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
29c70 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
29c80 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
29c90 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
29ca0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
29cb0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
29cc0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
29cd0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
29ce0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
29cf0 2a 2a 0a 2a 2a 20 7b 48 31 33 38 30 33 7d 20 54  **.** {H13803} T
29d00 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
29d10 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 69 6e  mn_blob(S,N)] in
29d20 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
29d30 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
29d40 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
29d50 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
29d60 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
29d70 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
29d80 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
29d90 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
29da0 20 61 20 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e   a BLOB and then
29db0 20 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20   returns a.**   
29dc0 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74         pointer t
29dd0 6f 20 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20  o the converted 
29de0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  value..**.** {H1
29df0 33 38 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  3806} The [sqlit
29e00 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
29e10 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
29e20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20  returns the.**  
29e30 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20 6f          number o
29e40 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 42  f bytes in the B
29e50 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 28 65  LOB or string (e
29e60 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a  xclusive of the.
29e70 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f  **          zero
29e80 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74   terminator on t
29e90 68 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20  he string) that 
29ea0 77 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  was returned by 
29eb0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
29ec0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
29ed0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   to [sqlite3_col
29ee0 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e 29 5d 20 6f  umn_blob(S,N)] o
29ef0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
29f00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
29f10 78 74 28 53 2c 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20  xt(S,N)]..**.** 
29f20 7b 48 31 33 38 30 39 7d 20 54 68 65 20 5b 73 71  {H13809} The [sq
29f30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
29f40 65 73 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  es16(S,N)] inter
29f50 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
29f60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
29f70 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
29f80 74 68 65 20 73 74 72 69 6e 67 20 28 65 78 63 6c  the string (excl
29f90 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20  usive of the.** 
29fa0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65           zero te
29fb0 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20  rminator on the 
29fc0 73 74 72 69 6e 67 29 20 74 68 61 74 20 77 61 73  string) that was
29fd0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
29fe0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73  .**          mos
29ff0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2a000 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2a010 5f 74 65 78 74 31 36 28 53 2c 4e 29 5d 2e 0a 2a  _text16(S,N)]..*
2a020 2a 0a 2a 2a 20 7b 48 31 33 38 31 32 7d 20 54 68  *.** {H13812} Th
2a030 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2a040 6e 5f 64 6f 75 62 6c 65 28 53 2c 4e 29 5d 20 69  n_double(S,N)] i
2a050 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2a060 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2a070 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20    Nth column in 
2a080 74 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20  the current row 
2a090 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2a0a0 74 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  t for the.**    
2a0b0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
2a0c0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74  statement] S int
2a0d0 6f 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  o a floating poi
2a0e0 6e 74 20 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20  nt value and.** 
2a0f0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
2a100 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20   a copy of that 
2a110 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  value..**.** {H1
2a120 33 38 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74  3815} The [sqlit
2a130 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 53 2c  e3_column_int(S,
2a140 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
2a150 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2a160 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
2a170 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
2a180 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2a190 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a  lt set for the.*
2a1a0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2a1b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a1c0 53 20 69 6e 74 6f 20 61 20 36 34 2d 62 69 74 20  S into a 64-bit 
2a1d0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
2a1e0 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  nd.**          r
2a1f0 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77 65 72  eturns the lower
2a200 20 33 32 20 62 69 74 73 20 6f 66 20 74 68 61 74   32 bits of that
2a210 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
2a220 7b 48 31 33 38 31 38 7d 20 54 68 65 20 5b 73 71  {H13818} The [sq
2a230 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2a240 36 34 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  64(S,N)] interfa
2a250 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2a260 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
2a270 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
2a280 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2a290 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20   result set for 
2a2a0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2a2b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a2c0 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34  ent] S into a 64
2a2d0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2a2e0 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ger and.**      
2a2f0 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 63 6f      returns a co
2a300 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74 65 67  py of that integ
2a310 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 32  er..**.** {H1382
2a320 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
2a330 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 53 2c 4e 29  column_text(S,N)
2a340 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76  ] interface conv
2a350 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  erts the.**     
2a360 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20       Nth column 
2a370 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  in the current r
2a380 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
2a390 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20 20   set for.**     
2a3a0 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61 72       the [prepar
2a3b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
2a3c0 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
2a3d0 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
2a3e0 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2a3f0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
2a400 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
2a410 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ring..**.** {H13
2a420 38 32 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  824} The [sqlite
2a430 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2a440 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2a450 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
2a460 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c           Nth col
2a470 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65  umn in the curre
2a480 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2a490 73 75 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65  sult set for the
2a4a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2a4b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a4c0 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f 2d  ] S into a zero-
2a4d0 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79 74  terminated 2-byt
2a4e0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c  e.**          al
2a4f0 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61 74  igned UTF-16 nat
2a500 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 73  ive byte order s
2a510 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2a520 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  s.**          a 
2a530 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20  pointer to that 
2a540 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  string..**.** {H
2a550 31 33 38 32 37 7d 20 54 68 65 20 5b 73 71 6c 69  13827} The [sqli
2a560 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2a570 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2a580 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
2a590 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49      one of [SQLI
2a5a0 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_NULL], [SQLIT
2a5b0 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c  E_INTEGER], [SQL
2a5c0 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20  ITE_FLOAT],.**  
2a5d0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
2a5e0 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  TEXT], or [SQLIT
2a5f0 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f  E_BLOB] as appro
2a600 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20  priate for.**   
2a610 20 20 20 20 20 20 20 74 68 65 20 4e 74 68 20 63         the Nth c
2a620 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
2a630 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2a640 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a  result set for.*
2a650 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
2a660 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a670 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  nt] S..**.** {H1
2a680 33 38 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74  3830} The [sqlit
2a690 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2a6a0 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  S,N)] interface 
2a6b0 72 65 74 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20  returns a.**    
2a6c0 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 74 6f        pointer to
2a6d0 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
2a6e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2a6f0 6f 62 6a 65 63 74 20 66 6f 72 20 74 68 65 0a 2a  object for the.*
2a700 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63  *          Nth c
2a710 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
2a720 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2a730 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a  result set for.*
2a740 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b  *          the [
2a750 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a760 6e 74 5d 20 53 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  nt] S..*/.const 
2a770 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2a780 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
2a790 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2a7a0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2a7b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
2a7c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2a7d0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2a7e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2a7f0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2a800 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
2a810 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
2a820 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
2a830 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2a840 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2a850 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
2a860 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2a870 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
2a880 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
2a890 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
2a8a0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2a8b0 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
2a8c0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2a8d0 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
2a8e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2a8f0 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
2a900 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a910 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2a920 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2a930 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2a940 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
2a950 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2a960 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
2a970 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2a980 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
2a990 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2a9a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a9b0 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
2a9c0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
2a9d0 6a 65 63 74 20 7b 48 31 33 33 30 30 7d 20 3c 53  ject {H13300} <S
2a9e0 37 30 33 30 30 3e 3c 53 33 30 31 30 30 3e 0a 2a  70300><S30100>.*
2a9f0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2aa00 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
2aa10 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
2aa20 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
2aa30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2aa40 0a 2a 2a 20 49 66 20 74 68 65 20 73 74 61 74 65  .** If the state
2aa50 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75 74 65  ment was execute
2aa60 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f  d successfully o
2aa70 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61  r not executed a
2aa80 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53  t all, then.** S
2aa90 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75  QLITE_OK is retu
2aaa0 72 6e 65 64 2e 20 49 66 20 65 78 65 63 75 74 69  rned. If executi
2aab0 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
2aac0 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e 20  ent failed then 
2aad0 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
2aae0 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  e] or [extended 
2aaf0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2ab00 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
2ab10 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
2ab20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
2ab30 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74 68   point during th
2ab40 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  e execution of t
2ab50 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2ab60 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66 20  statement].  If 
2ab70 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68  the virtual mach
2ab80 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63  ine has not.** c
2ab90 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
2aba0 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75  on when this rou
2abb0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20  tine is called, 
2abc0 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20  that is like.** 
2abd0 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20  encountering an 
2abe0 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c  error or an [sql
2abf0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c  ite3_interrupt |
2ac00 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20   interrupt]..** 
2ac10 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74  Incomplete updat
2ac20 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64  es may be rolled
2ac30 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61   back and transa
2ac40 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c  ctions canceled,
2ac50 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  .** depending on
2ac60 20 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63   the circumstanc
2ac70 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b  es, and the.** [
2ac80 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75  error code] retu
2ac90 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51  rned will be [SQ
2aca0 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a  LITE_ABORT]..**.
2acb0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
2acc0 2a 0a 2a 2a 20 7b 48 31 31 33 30 32 7d 20 54 68  *.** {H11302} Th
2acd0 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  e [sqlite3_final
2ace0 69 7a 65 28 53 29 5d 20 69 6e 74 65 72 66 61 63  ize(S)] interfac
2acf0 65 20 64 65 73 74 72 6f 79 73 20 74 68 65 0a 2a  e destroys the.*
2ad00 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2ad10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ad20 53 20 61 6e 64 20 72 65 6c 65 61 73 65 73 20 61  S and releases a
2ad30 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  ll.**          m
2ad40 65 6d 6f 72 79 20 61 6e 64 20 66 69 6c 65 20 72  emory and file r
2ad50 65 73 6f 75 72 63 65 73 20 68 65 6c 64 20 62 79  esources held by
2ad60 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 0a 2a 2a   that object..**
2ad70 0a 2a 2a 20 7b 48 31 31 33 30 34 7d 20 49 66 20  .** {H11304} If 
2ad80 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2ad90 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2ada0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
2adb0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70  e.**          [p
2adc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2add0 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 61 6e  t] S returned an
2ade0 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20 20 20   error,.**      
2adf0 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65      then [sqlite
2ae00 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 72  3_finalize(S)] r
2ae10 65 74 75 72 6e 73 20 74 68 61 74 20 73 61 6d 65  eturns that same
2ae20 20 65 72 72 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73   error..*/.int s
2ae30 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2ae40 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2ae50 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2ae60 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
2ae70 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2ae80 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 33 30  t Object {H13330
2ae90 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70300>.**.**
2aea0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2aeb0 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
2aec0 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
2aed0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2aee0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
2aef0 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
2af00 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
2af10 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
2af20 75 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c  uted..** Any SQL
2af30 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
2af40 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
2af50 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
2af60 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
2af70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2af80 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
2af90 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
2afa0 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
2afb0 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
2afc0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
2afd0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
2afe0 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b  indings..**.** {
2aff0 48 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71 6c  H11332} The [sql
2b000 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
2b010 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
2b020 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2b030 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20  atement] S.**   
2b040 20 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20 74         back to t
2b050 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
2b060 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
2b070 2a 2a 20 7b 48 31 31 33 33 34 7d 20 49 66 20 74  ** {H11334} If t
2b080 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2b090 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2b0a0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
2b0b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2b0c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b0d0 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
2b0e0 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
2b0f0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20  LITE_DONE],.**  
2b100 20 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73          or if [s
2b110 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2b120 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65  has never before
2b130 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20   been called on 
2b140 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  S,.**          t
2b150 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
2b160 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
2b170 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
2b180 2a 20 7b 48 31 31 33 33 36 7d 20 49 66 20 74 68  * {H11336} If th
2b190 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2b1a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2b1b0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
2b1c0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
2b1d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b1e0 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
2b1f0 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20  error, then.**  
2b200 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2b210 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
2b220 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
2b230 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
2b240 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d 20 54  **.** {H11338} T
2b250 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2b260 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
2b270 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
2b280 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20  the values.**   
2b290 20 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b 73         of any [s
2b2a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2b2b0 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
2b2c0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2b2d0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
2b2e0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
2b2f0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2b300 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2b310 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
2b320 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
2b330 63 74 69 6f 6e 73 20 7b 48 31 36 31 30 30 7d 20  ctions {H16100} 
2b340 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S20200>.** KEYW
2b350 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
2b360 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
2b370 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
2b380 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2b390 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2b3a0 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
2b3b0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2b3c0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2b3d0 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
2b3e0 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  two functions (c
2b3f0 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
2b400 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
2b410 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
2b420 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
2b430 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
2b440 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
2b450 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
2b460 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
2b470 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
2b480 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
2b490 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
2b4a0 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 62  nly difference b
2b4b0 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77  etween the.** tw
2b4c0 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65  o is that the se
2b4d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20  cond parameter, 
2b4e0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2b4f0 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f  (scalar) functio
2b500 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2b510 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e  e, is encoded in
2b520 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74   UTF-8 for sqlit
2b530 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2b540 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a  on() and UTF-16.
2b550 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
2b560 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2b570 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ()..**.** The fi
2b580 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
2b590 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2b5a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
2b5b0 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
2b5c0 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
2b5d0 20 61 64 64 65 64 2e 20 20 49 66 20 61 20 73 69   added.  If a si
2b5e0 6e 67 6c 65 20 70 72 6f 67 72 61 6d 20 75 73 65  ngle program use
2b5f0 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
2b600 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
2b610 65 63 74 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c  ection internall
2b620 79 2c 20 74 68 65 6e 20 53 51 4c 20 66 75 6e 63  y, then SQL func
2b630 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
2b640 64 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ded individually
2b650 20 74 6f 0a 2a 2a 20 65 61 63 68 20 64 61 74 61   to.** each data
2b660 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
2b670 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
2b680 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
2b690 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
2b6a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
2b6b0 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
2b6c0 72 65 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20  redefined.  The 
2b6d0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
2b6e0 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
2b6f0 20 32 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c   255 bytes, excl
2b700 75 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20  usive of.** the 
2b710 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e  zero-terminator.
2b720 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
2b730 6e 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69  name length limi
2b740 74 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e  t is in bytes, n
2b750 6f 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  ot.** characters
2b760 2e 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  .  Any attempt t
2b770 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
2b780 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
2b790 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
2b7a0 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
2b7b0 5f 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72 65  _ERROR] being re
2b7c0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
2b7d0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2b7e0 72 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  r is the number 
2b7f0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
2b800 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2b810 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
2b820 74 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69  te takes. If thi
2b830 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  s parameter is n
2b840 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
2b850 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2b860 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
2b870 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
2b880 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e  er of arguments.
2b890 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74  .**.** The fourt
2b8a0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
2b8b0 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
2b8c0 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
2b8d0 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
2b8e0 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
2b8f0 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
2b900 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
2b910 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c  meters.  Any SQL
2b920 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2b930 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
2b940 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a  be able to work.
2b950 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46  ** work with UTF
2b960 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72  -8, UTF-16le, or
2b970 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20   UTF-16be.  But 
2b980 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  some implementat
2b990 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d  ions may be.** m
2b9a0 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69  ore efficient wi
2b9b0 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20  th one encoding 
2b9c0 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49  than another.  I
2b9d0 74 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a  t is allowed to.
2b9e0 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
2b9f0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2ba00 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  n() or sqlite3_c
2ba10 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2ba20 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  () multiple.** t
2ba30 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
2ba40 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20  me function but 
2ba50 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76  with different v
2ba60 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65  alues of eTextRe
2ba70 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69  p..** When multi
2ba80 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
2ba90 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
2baa0 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
2bab0 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
2bac0 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
2bad0 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
2bae0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
2baf0 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
2bb00 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
2bb10 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
2bb20 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
2bb30 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
2bb40 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74  t care what text
2bb50 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  .** encoding is 
2bb60 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
2bb70 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
2bb80 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45  hould be [SQLITE
2bb90 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  _ANY]..**.** The
2bba0 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
2bbb0 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
2bbc0 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69   pointer.  The i
2bbd0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2bbe0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
2bbf0 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73   can gain access
2bc00 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72   to this pointer
2bc10 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2bc20 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a  user_data()]..**
2bc30 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c  .** The seventh,
2bc40 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74   eighth and nint
2bc50 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
2bc60 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
2bc70 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
2bc80 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
2bc90 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
2bca0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
2bcb0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2bcc0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
2bcd0 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  A scalar SQL fun
2bce0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
2bcf0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2bd00 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a   of the xFunc.**
2bd10 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20   callback only, 
2bd20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68  NULL pointers sh
2bd30 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 61  ould be passed a
2bd40 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
2bd50 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
2bd60 74 65 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61  ters. An aggrega
2bd70 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
2bd80 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
2bd90 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
2bda0 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
2bdb0 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c  l and NULL shoul
2bdc0 64 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20  d be passed for 
2bdd0 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65  xFunc. To delete
2bde0 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20   an existing.** 
2bdf0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
2be00 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20  aggregate, pass 
2be10 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72  NULL for all thr
2be20 65 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ee function call
2be30 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  backs..**.** It 
2be40 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
2be50 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
2be60 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2be70 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
2be80 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
2be90 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
2bea0 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
2beb0 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
2bec0 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
2bed0 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65  or differing pre
2bee0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
2bef0 64 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77  dings.  SQLite w
2bf00 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
2bf10 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f  mplementation mo
2bf20 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
2bf30 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
2bf40 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
2bf50 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
2bf60 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
2bf70 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 33  S:.**.** {H16103
2bf80 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2bf90 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2bfa0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
2bfb0 68 61 76 65 73 20 65 78 61 63 74 6c 79 0a 2a 2a  haves exactly.**
2bfc0 20 20 20 20 20 20 20 20 20 20 6c 69 6b 65 20 5b            like [
2bfd0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2bfe0 75 6e 63 74 69 6f 6e 28 29 5d 20 69 6e 20 65 76  unction()] in ev
2bff0 65 72 79 20 77 61 79 20 65 78 63 65 70 74 20 74  ery way except t
2c000 68 61 74 20 69 74 0a 2a 2a 20 20 20 20 20 20 20  hat it.**       
2c010 20 20 20 69 6e 74 65 72 70 72 65 74 73 20 74 68     interprets th
2c020 65 20 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 20  e zFunctionName 
2c030 61 72 67 75 6d 65 6e 74 20 61 73 20 7a 65 72 6f  argument as zero
2c040 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
2c050 31 36 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  16.**          n
2c060 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2c070 20 69 6e 73 74 65 61 64 20 6f 66 20 61 73 20 7a   instead of as z
2c080 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
2c090 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  TF-8..**.** {H16
2c0a0 31 30 36 7d 20 41 20 73 75 63 63 65 73 73 66 75  106} A successfu
2c0b0 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  l invocation of.
2c0c0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2c0d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2c0e0 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
2c0f0 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65  ,...)] interface
2c100 20 72 65 67 69 73 74 65 72 73 0a 2a 2a 20 20 20   registers.**   
2c110 20 20 20 20 20 20 20 6f 72 20 72 65 70 6c 61 63         or replac
2c120 65 73 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  es callback func
2c130 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 5b 64 61  tions in the [da
2c140 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2c150 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20  n] D.**         
2c160 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
2c170 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
2c180 69 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68  ion named X with
2c190 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a   N parameters.**
2c1a0 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 68 61            and ha
2c1b0 76 69 6e 67 20 61 20 70 72 65 66 65 72 72 65 64  ving a preferred
2c1c0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 6f   text encoding o
2c1d0 66 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31  f E..**.** {H161
2c1e0 30 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  09} A successful
2c1f0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2c200 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2c210 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  n(D,X,N,E,P,F,S,
2c220 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  L)].**          
2c230 72 65 70 6c 61 63 65 73 20 74 68 65 20 50 2c 20  replaces the P, 
2c240 46 2c 20 53 2c 20 61 6e 64 20 4c 20 76 61 6c 75  F, S, and L valu
2c250 65 73 20 66 72 6f 6d 20 61 6e 79 20 70 72 69 6f  es from any prio
2c260 72 20 63 61 6c 6c 73 20 77 69 74 68 0a 2a 2a 20  r calls with.** 
2c270 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d           the sam
2c280 65 20 44 2c 20 58 2c 20 4e 2c 20 61 6e 64 20 45  e D, X, N, and E
2c290 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b   values..**.** {
2c2a0 48 31 36 31 31 32 7d 20 54 68 65 20 5b 73 71 6c  H16112} The [sql
2c2b0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2c2c0 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e 29 5d 20 69  tion(D,X,...)] i
2c2d0 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
2c2e0 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
2c2f0 61 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66  a return code of
2c300 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2c310 69 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  if the SQL funct
2c320 69 6f 6e 20 6e 61 6d 65 20 58 20 69 73 0a 2a 2a  ion name X is.**
2c330 20 20 20 20 20 20 20 20 20 20 6c 6f 6e 67 65 72            longer
2c340 20 74 68 61 6e 20 32 35 35 20 62 79 74 65 73 20   than 255 bytes 
2c350 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
2c360 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2c370 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 31 38 7d  ..**.** {H16118}
2c380 20 45 69 74 68 65 72 20 46 20 6d 75 73 74 20 62   Either F must b
2c390 65 20 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64  e NULL and S and
2c3a0 20 4c 20 61 72 65 20 6e 6f 6e 2d 4e 55 4c 4c 20   L are non-NULL 
2c3b0 6f 72 20 65 6c 73 65 20 46 0a 2a 2a 20 20 20 20  or else F.**    
2c3c0 20 20 20 20 20 20 69 73 20 6e 6f 6e 2d 4e 55 4c        is non-NUL
2c3d0 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c 20 61 72  L and S and L ar
2c3e0 65 20 4e 55 4c 4c 2c 20 6f 74 68 65 72 77 69 73  e NULL, otherwis
2c3f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
2c400 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2c410 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50  nction(D,X,N,E,P
2c420 2c 46 2c 53 2c 4c 29 5d 20 72 65 74 75 72 6e 73  ,F,S,L)] returns
2c430 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
2c440 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 31 7d 20  .**.** {H16121} 
2c450 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  The [sqlite3_cre
2c460 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 2e  ate_function(D,.
2c470 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 66  ..)] interface f
2c480 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20  ails with an.** 
2c490 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 63           error c
2c4a0 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42  ode of [SQLITE_B
2c4b0 55 53 59 5d 20 69 66 20 74 68 65 72 65 20 65 78  USY] if there ex
2c4c0 69 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  ist [prepared st
2c4d0 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20  atements].**    
2c4e0 20 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 64        associated
2c4f0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
2c500 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2c510 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 34  D..**.** {H16124
2c520 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2c530 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2c540 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  ,X,N,...)] inter
2c550 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
2c560 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65  an.**          e
2c570 72 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51  rror code of [SQ
2c580 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 70  LITE_ERROR] if p
2c590 61 72 61 6d 65 74 65 72 20 4e 20 28 73 70 65 63  arameter N (spec
2c5a0 69 66 79 69 6e 67 20 74 68 65 20 6e 75 6d 62 65  ifying the numbe
2c5b0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  r.**          of
2c5c0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
2c5d0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 62  e SQL function b
2c5e0 65 69 6e 67 20 72 65 67 69 73 74 65 72 65 64 29  eing registered)
2c5f0 20 69 73 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20   is less.**     
2c600 20 20 20 20 20 74 68 61 6e 20 2d 31 20 6f 72 20       than -1 or 
2c610 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37  greater than 127
2c620 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 37 7d  ..**.** {H16127}
2c630 20 57 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e   When N is non-n
2c640 65 67 61 74 69 76 65 2c 20 74 68 65 20 5b 73 71  egative, the [sq
2c650 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2c660 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29  ction(D,X,N,...)
2c670 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
2c680 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 63  terface causes c
2c690 61 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69  allbacks to be i
2c6a0 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53  nvoked for the S
2c6b0 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20  QL function.**  
2c6c0 20 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20          named X 
2c6d0 77 68 65 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  when the number 
2c6e0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  of arguments to 
2c6f0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2c700 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
2c710 65 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a 0a 2a 2a  exactly N..**.**
2c720 20 7b 48 31 36 31 33 30 7d 20 57 68 65 6e 20 4e   {H16130} When N
2c730 20 69 73 20 2d 31 2c 20 74 68 65 20 5b 73 71 6c   is -1, the [sql
2c740 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2c750 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
2c760 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
2c770 65 72 66 61 63 65 20 63 61 75 73 65 73 20 63 61  erface causes ca
2c780 6c 6c 62 61 63 6b 73 20 74 6f 20 62 65 20 69 6e  llbacks to be in
2c790 76 6f 6b 65 64 20 66 6f 72 20 74 68 65 20 53 51  voked for the SQ
2c7a0 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  L function.**   
2c7b0 20 20 20 20 20 20 20 6e 61 6d 65 64 20 58 20 77         named X w
2c7c0 69 74 68 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ith any number o
2c7d0 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  f arguments..**.
2c7e0 2a 2a 20 7b 48 31 36 31 33 33 7d 20 57 68 65 6e  ** {H16133} When
2c7f0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [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 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a  on(D,X,N,...)].*
2c820 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63 69  *          speci
2c830 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  fy multiple impl
2c840 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
2c850 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2c860 20 58 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61   X.**          a
2c870 6e 64 20 77 68 65 6e 20 6f 6e 65 20 69 6d 70 6c  nd when one impl
2c880 65 6d 65 6e 74 61 74 69 6f 6e 20 68 61 73 20 4e  ementation has N
2c890 3e 3d 30 20 61 6e 64 20 74 68 65 20 6f 74 68 65  >=0 and the othe
2c8a0 72 20 68 61 73 20 4e 3d 28 2d 31 29 0a 2a 2a 20  r has N=(-1).** 
2c8b0 20 20 20 20 20 20 20 20 20 74 68 65 20 69 6d 70           the imp
2c8c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
2c8d0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 4e 20 69 73   a non-zero N is
2c8e0 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a   preferred..**.*
2c8f0 2a 20 7b 48 31 36 31 33 36 7d 20 57 68 65 6e 20  * {H16136} When 
2c900 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2c910 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2c920 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d 0a  n(D,X,N,E,...)].
2c930 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70 65 63  **          spec
2c940 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ify multiple imp
2c950 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
2c960 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2c970 6e 20 58 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  n X with.**     
2c980 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 6e 75       the same nu
2c990 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
2c9a0 73 20 4e 20 62 75 74 20 77 69 74 68 20 64 69 66  s N but with dif
2c9b0 66 65 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20  ferent.**       
2c9c0 20 20 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c 20     encodings E, 
2c9d0 74 68 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65  then the impleme
2c9e0 6e 74 61 74 69 6f 6e 20 77 68 65 72 65 20 45 20  ntation where E 
2c9f0 6d 61 74 63 68 65 73 20 74 68 65 0a 2a 2a 20 20  matches the.**  
2ca00 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65          database
2ca10 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 70 72 65   encoding is pre
2ca20 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ferred..**.** {H
2ca30 31 36 31 33 39 7d 20 46 6f 72 20 61 6e 20 61 67  16139} For an ag
2ca40 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
2ca50 74 69 6f 6e 20 63 72 65 61 74 65 64 20 75 73 69  tion created usi
2ca60 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ng.**          [
2ca70 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2ca80 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c  unction(D,X,N,E,
2ca90 50 2c 30 2c 53 2c 4c 29 5d 20 74 68 65 20 66 69  P,0,S,L)] the fi
2caa0 6e 61 6c 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20  nalizer.**      
2cab0 20 20 20 20 66 75 6e 63 74 69 6f 6e 20 4c 20 77      function L w
2cac0 69 6c 6c 20 61 6c 77 61 79 73 20 62 65 20 69 6e  ill always be in
2cad0 76 6f 6b 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  voked exactly on
2cae0 63 65 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20  ce if the.**    
2caf0 20 20 20 20 20 20 73 74 65 70 20 66 75 6e 63 74        step funct
2cb00 69 6f 6e 20 53 20 69 73 20 63 61 6c 6c 65 64 20  ion S is called 
2cb10 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
2cb20 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 34 32  s..**.** {H16142
2cb30 7d 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  } When SQLite in
2cb40 76 6f 6b 65 73 20 65 69 74 68 65 72 20 74 68 65  vokes either the
2cb50 20 78 46 75 6e 63 20 6f 72 20 78 53 74 65 70 20   xFunc or xStep 
2cb60 66 75 6e 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 20  function of.**  
2cb70 20 20 20 20 20 20 20 20 61 6e 20 61 70 70 6c 69          an appli
2cb80 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2cb90 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
2cba0 67 67 72 65 67 61 74 65 20 63 72 65 61 74 65 64  ggregate created
2cbb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20  .**          by 
2cbc0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2cbd0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 6f 72 20 5b  function()] or [
2cbe0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2cbf0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 0a 2a 2a  unction16()],.**
2cc00 20 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 74            then t
2cc10 68 65 20 61 72 72 61 79 20 6f 66 20 5b 73 71 6c  he array of [sql
2cc20 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2cc30 63 74 73 20 70 61 73 73 65 64 20 61 73 20 74 68  cts passed as th
2cc40 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  e.**          th
2cc50 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  ird parameter ar
2cc60 65 20 61 6c 77 61 79 73 20 5b 70 72 6f 74 65 63  e always [protec
2cc70 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2cc80 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 69  e] objects..*/.i
2cc90 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2cca0 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
2ccb0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
2ccc0 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
2ccd0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
2cce0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
2ccf0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
2cd00 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
2cd10 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2cd20 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2cd30 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2cd40 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
2cd50 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2cd60 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2cd70 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
2cd80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2cd90 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
2cda0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2cdb0 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  n16(.  sqlite3 *
2cdc0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  db,.  const void
2cdd0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
2cde0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
2cdf0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
2ce00 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
2ce10 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
2ce20 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2ce30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2ce40 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
2ce50 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2ce60 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2ce70 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2ce80 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
2ce90 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a  3_context*).);..
2cea0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ceb0 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b  Text Encodings {
2cec0 48 31 30 32 36 37 7d 20 3c 53 35 30 32 30 30 3e  H10267} <S50200>
2ced0 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H16100>.**.** 
2cee0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64  These constant d
2cef0 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f  efine integer co
2cf00 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65  des that represe
2cf10 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a  nt the various.*
2cf20 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  * text encodings
2cf30 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
2cf40 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
2cf50 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20   SQLITE_UTF8    
2cf60 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
2cf70 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
2cf80 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
2cf90 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20   SQLITE_UTF16BE 
2cfa0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
2cfb0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20   SQLITE_UTF16   
2cfc0 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55         4    /* U
2cfd0 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  se native byte o
2cfe0 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rder */.#define 
2cff0 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20  SQLITE_ANY      
2d000 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71        5    /* sq
2d010 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2d020 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64  ction only */.#d
2d030 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
2d040 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20  16_ALIGNED  8   
2d050 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
2d060 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c  te_collation onl
2d070 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  y */../*.** CAPI
2d080 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
2d090 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
2d0a0 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
2d0b0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
2d0c0 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
2d0d0 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
2d0e0 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
2d0f0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
2d100 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
2d110 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
2d120 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
2d130 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
2d140 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
2d150 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2d160 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
2d170 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
2d180 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70  ctions.  To help
2d190 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c   encourage peopl
2d1a0 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73  e to avoid.** us
2d1b0 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69  ing these functi
2d1c0 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20  ons, we are not 
2d1d0 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f  going to tell yo
2d1e0 75 20 77 61 6e 74 20 74 68 65 79 20 64 6f 2e 0a  u want they do..
2d1f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  */.int sqlite3_a
2d200 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
2d210 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2d220 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  ;.int sqlite3_ex
2d230 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
2d240 6d 74 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  mt*);.int sqlite
2d250 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
2d260 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
2d270 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
2d280 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  );.int sqlite3_g
2d290 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
2d2a0 69 64 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  id);.void sqlite
2d2b0 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70  3_thread_cleanup
2d2c0 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
2d2d0 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
2d2e0 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73  (void(*)(void*,s
2d2f0 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74  qlite3_int64,int
2d300 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  ),void*,sqlite3_
2d310 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int64);../*.** C
2d320 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
2d330 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  ng SQL Function 
2d340 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73  Parameter Values
2d350 20 7b 48 31 35 31 30 30 7d 20 3c 53 32 30 32 30   {H15100} <S2020
2d360 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  0>.**.** The C-l
2d370 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
2d380 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
2d390 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
2d3a0 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
2d3b0 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
2d3c0 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
2d3d0 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
2d3e0 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
2d3f0 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
2d400 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
2d410 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
2d420 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
2d430 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
2d440 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
2d450 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
2d460 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2d470 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
2d480 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2d490 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
2d4a0 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
2d4b0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
2d4c0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2d4d0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
2d4e0 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61  s..** The 4th pa
2d4f0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
2d500 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
2d510 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
2d520 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
2d530 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2d540 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
2d550 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
2d560 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2d570 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
2d580 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
2d590 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
2d5a0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2d5b0 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
2d5c0 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
2d5d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2d5e0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
2d5f0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2d600 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
2d610 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2d620 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2d630 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
2d640 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
2d650 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
2d660 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2d670 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
2d680 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
2d690 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
2d6a0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  r..**.** These r
2d6b0 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
2d6c0 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
2d6d0 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
2d6e0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2d6f0 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
2d700 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  t  these routine
2d710 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
2d720 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2d730 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2d740 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
2d750 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
2d760 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
2d770 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
2d780 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
2d790 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2d7a0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
2d7b0 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
2d7c0 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
2d7d0 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
2d7e0 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
2d7f0 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
2d800 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ne.  The.** sqli
2d810 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2d820 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
2d830 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
2d840 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
2d850 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
2d860 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
2d870 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
2d880 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
2d890 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
2d8a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
2d8b0 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
2d8c0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
2d8d0 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
2d8e0 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
2d8f0 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
2d900 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
2d910 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
2d920 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
2d930 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
2d940 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
2d950 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
2d960 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
2d970 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
2d980 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
2d990 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
2d9a0 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
2d9b0 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
2d9c0 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
2d9d0 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
2d9e0 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
2d9f0 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
2da00 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
2da10 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
2da20 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
2da30 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
2da40 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
2da50 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
2da60 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61  rned..**.** Plea
2da70 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61  se pay particula
2da80 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74  r attention to t
2da90 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65  he fact that the
2daa0 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65   pointer returne
2dab0 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
2dac0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d  e3_value_blob()]
2dad0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2dae0 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20  _text()], or.** 
2daf0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2db00 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20  ext16()] can be 
2db10 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61  invalidated by a
2db20 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
2db30 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2db40 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
2db50 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2db60 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69  ytes16()], [sqli
2db70 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
2db80 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
2db90 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
2dba0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ]..**.** These r
2dbb0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
2dbc0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
2dbd0 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a  same thread as.*
2dbe0 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
2dbf0 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64  on that supplied
2dc00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2dc10 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73  lue*] parameters
2dc20 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2dc30 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30  TS:.**.** {H1510
2dc40 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
2dc50 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29 5d 20 69  value_blob(V)] i
2dc60 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2dc70 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2dc80 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2dc90 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2dca0 63 74 20 56 20 69 6e 74 6f 20 61 20 42 4c 4f 42  ct V into a BLOB
2dcb0 20 61 6e 64 20 74 68 65 6e 0a 2a 2a 20 20 20 20   and then.**    
2dcc0 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
2dcd0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63  pointer to the c
2dce0 6f 6e 76 65 72 74 65 64 20 76 61 6c 75 65 2e 0a  onverted value..
2dcf0 2a 2a 0a 2a 2a 20 7b 48 31 35 31 30 36 7d 20 54  **.** {H15106} T
2dd00 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2dd10 65 5f 62 79 74 65 73 28 56 29 5d 20 69 6e 74 65  e_bytes(V)] inte
2dd20 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2dd30 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75  e.**          nu
2dd40 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2dd50 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
2dd60 69 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f  ing (exclusive o
2dd70 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  f the.**        
2dd80 20 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f    zero terminato
2dd90 72 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29  r on the string)
2dda0 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
2ddb0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20  ed by the.**    
2ddc0 20 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e        most recen
2ddd0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2dde0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 56 29  e3_value_blob(V)
2ddf0 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
2de00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2de10 74 65 78 74 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20  text(V)]..**.** 
2de20 7b 48 31 35 31 30 39 7d 20 54 68 65 20 5b 73 71  {H15109} The [sq
2de30 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2de40 73 31 36 28 56 29 5d 20 69 6e 74 65 72 66 61 63  s16(V)] interfac
2de50 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2de60 20 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72            number
2de70 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2de80 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73 69   string (exclusi
2de90 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20  ve of the.**    
2dea0 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d 69        zero termi
2deb0 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74 72  nator on the str
2dec0 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72 65  ing) that was re
2ded0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
2dee0 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20 72            most r
2def0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2df00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2df10 74 31 36 28 56 29 5d 2c 0a 2a 2a 20 20 20 20 20  t16(V)],.**     
2df20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76 61       [sqlite3_va
2df30 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56 29 5d  lue_text16be(V)]
2df40 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  , or [sqlite3_va
2df50 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 56 29 5d  lue_text16le(V)]
2df60 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31 32 7d  ..**.** {H15112}
2df70 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2df80 6c 75 65 5f 64 6f 75 62 6c 65 28 56 29 5d 20 69  lue_double(V)] i
2df90 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
2dfa0 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2dfb0 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
2dfc0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2dfd0 63 74 20 56 20 69 6e 74 6f 20 61 20 66 6c 6f 61  ct V into a floa
2dfe0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2dff0 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
2e000 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
2e010 6f 66 20 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a  of that value..*
2e020 2a 0a 2a 2a 20 7b 48 31 35 31 31 35 7d 20 54 68  *.** {H15115} Th
2e030 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2e040 5f 69 6e 74 28 56 29 5d 20 69 6e 74 65 72 66 61  _int(V)] interfa
2e050 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2e060 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f  **          [pro
2e070 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2e080 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69  alue] object V i
2e090 6e 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67  nto a 64-bit sig
2e0a0 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a  ned integer and.
2e0b0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
2e0c0 72 6e 73 20 74 68 65 20 6c 6f 77 65 72 20 33 32  rns the lower 32
2e0d0 20 62 69 74 73 20 6f 66 20 74 68 61 74 20 69 6e   bits of that in
2e0e0 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  teger..**.** {H1
2e0f0 35 31 31 38 7d 20 54 68 65 20 5b 73 71 6c 69 74  5118} The [sqlit
2e100 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 56  e3_value_int64(V
2e110 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2e120 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2e130 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
2e140 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2e150 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
2e160 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2e170 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20  teger and.**    
2e180 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
2e190 63 6f 70 79 20 6f 66 20 74 68 61 74 20 69 6e 74  copy of that int
2e1a0 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  eger..**.** {H15
2e1b0 31 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  121} The [sqlite
2e1c0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 56 29 5d  3_value_text(V)]
2e1d0 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65   interface conve
2e1e0 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  rts the.**      
2e1f0 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73      [protected s
2e200 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2e210 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65  ject V into a ze
2e220 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
2e230 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  F-8.**          
2e240 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2e250 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2e260 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
2e270 2a 2a 20 7b 48 31 35 31 32 34 7d 20 54 68 65 20  ** {H15124} The 
2e280 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2e290 65 78 74 31 36 28 56 29 5d 20 69 6e 74 65 72 66  ext16(V)] interf
2e2a0 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
2e2b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
2e2c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e2d0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
2e2e0 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
2e2f0 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a  inated 2-byte.**
2e300 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65            aligne
2e310 64 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  d UTF-16 native 
2e320 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20 20 20  byte order.**   
2e330 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e         string an
2e340 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
2e350 74 65 72 20 74 6f 20 74 68 61 74 20 73 74 72 69  ter to that stri
2e360 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32  ng..**.** {H1512
2e370 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
2e380 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 56  value_text16be(V
2e390 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2e3a0 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2e3b0 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65 64        [protected
2e3c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2e3d0 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61 20  object V into a 
2e3e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2e3f0 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20  2-byte.**       
2e400 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31     aligned UTF-1
2e410 36 20 62 69 67 2d 65 6e 64 69 61 6e 0a 2a 2a 20  6 big-endian.** 
2e420 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
2e430 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
2e440 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 73 74  inter to that st
2e450 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35  ring..**.** {H15
2e460 31 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  130} The [sqlite
2e470 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
2e480 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  (V)] interface c
2e490 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20  onverts the.**  
2e4a0 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
2e4b0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2e4c0 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20  ] object V into 
2e4d0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2e4e0 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20  d 2-byte.**     
2e4f0 20 20 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46       aligned UTF
2e500 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  -16 little-endia
2e510 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  n.**          st
2e520 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2e530 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2e540 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
2e550 20 7b 48 31 35 31 33 33 7d 20 54 68 65 20 5b 73   {H15133} The [s
2e560 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
2e570 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(V)] interface 
2e580 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20  returns.**      
2e590 20 20 20 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49      one of [SQLI
2e5a0 54 45 5f 4e 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_NULL], [SQLIT
2e5b0 45 5f 49 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c  E_INTEGER], [SQL
2e5c0 49 54 45 5f 46 4c 4f 41 54 5d 2c 0a 2a 2a 20 20  ITE_FLOAT],.**  
2e5d0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
2e5e0 54 45 58 54 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  TEXT], or [SQLIT
2e5f0 45 5f 42 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f  E_BLOB] as appro
2e600 70 72 69 61 74 65 20 66 6f 72 0a 2a 2a 20 20 20  priate for.**   
2e610 20 20 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69         the [sqli
2e620 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2e630 74 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  t V..**.** {H151
2e640 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  36} The [sqlite3
2e650 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
2e660 79 70 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  ype(V)] interfac
2e670 65 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 20 20  e converts.**   
2e680 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 6f 74         the [prot
2e690 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e6a0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
2e6b0 74 6f 20 65 69 74 68 65 72 20 61 6e 20 69 6e 74  to either an int
2e6c0 65 67 65 72 20 6f 72 0a 2a 2a 20 20 20 20 20 20  eger or.**      
2e6d0 20 20 20 20 61 20 66 6c 6f 61 74 69 6e 67 20 70      a floating p
2e6e0 6f 69 6e 74 20 76 61 6c 75 65 20 69 66 20 69 74  oint value if it
2e6f0 20 63 61 6e 20 64 6f 20 73 6f 20 77 69 74 68 6f   can do so witho
2e700 75 74 20 6c 6f 73 73 20 6f 66 0a 2a 2a 20 20 20  ut loss of.**   
2e710 20 20 20 20 20 20 20 69 6e 66 6f 72 6d 61 74 69         informati
2e720 6f 6e 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  on, and returns 
2e730 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4e  one of [SQLITE_N
2e740 55 4c 4c 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ULL],.**        
2e750 20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45    [SQLITE_INTEGE
2e760 52 5d 2c 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  R], [SQLITE_FLOA
2e770 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
2e780 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
2e790 20 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20    [SQLITE_BLOB] 
2e7a0 61 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  as appropriate f
2e7b0 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
2e7c0 20 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71     [protected sq
2e7d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2e7e0 65 63 74 20 56 20 61 66 74 65 72 20 74 68 65 20  ect V after the 
2e7f0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 74 74 65 6d  conversion attem
2e800 70 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  pt..*/.const voi
2e810 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2e820 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
2e830 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2e840 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
2e850 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2e860 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2e870 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
2e880 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
2e890 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
2e8a0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
2e8b0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2e8c0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
2e8d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
2e8e0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
2e8f0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
2e900 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2e910 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
2e920 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
2e930 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
2e940 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
2e950 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
2e960 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
2e970 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
2e980 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2e990 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
2e9a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2e9b0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2e9c0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2e9d0 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
2e9e0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2e9f0 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
2ea00 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2ea10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
2ea20 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
2ea30 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
2ea40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
2ea50 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
2ea60 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
2ea70 7b 48 31 36 32 31 30 7d 20 3c 53 32 30 32 30 30  {H16210} <S20200
2ea80 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6d 70 6c  >.**.** The impl
2ea90 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 67  ementation of ag
2eaa0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
2eab0 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 20 72  tions use this r
2eac0 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
2ead0 74 65 0a 2a 2a 20 61 20 73 74 72 75 63 74 75 72  te.** a structur
2eae0 65 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  e for storing th
2eaf0 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
2eb00 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   The first time 
2eb10 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
2eb20 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
2eb30 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
2eb40 64 20 66 6f 72 20 61 0a 2a 2a 20 70 61 72 74 69  d for a.** parti
2eb50 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 2c  cular aggregate,
2eb60 20 53 51 4c 69 74 65 20 61 6c 6c 6f 63 61 74 65   SQLite allocate
2eb70 73 20 6e 42 79 74 65 73 20 6f 66 20 6d 65 6d 6f  s nBytes of memo
2eb80 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
2eb90 68 61 74 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61  hat.** memory, a
2eba0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
2ebb0 6e 74 65 72 20 74 6f 20 69 74 2e 20 4f 6e 20 73  nter to it. On s
2ebc0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
2ebd0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
2ebe0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2ebf0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
2ec00 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
2ec10 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 64  ate function ind
2ec20 65 78 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ex,.** the same 
2ec30 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
2ec40 65 64 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  ed. The implemen
2ec50 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 61 67  tation of the ag
2ec60 67 72 65 67 61 74 65 20 63 61 6e 20 75 73 65 0a  gregate can use.
2ec70 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 65 64 20  ** the returned 
2ec80 62 75 66 66 65 72 20 74 6f 20 61 63 63 75 6d 75  buffer to accumu
2ec90 6c 61 74 65 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  late data..**.**
2eca0 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
2ecb0 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
2ecc0 61 6c 6c 6f 63 61 74 65 64 20 62 75 66 66 65 72  allocated buffer
2ecd0 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
2ece0 61 74 65 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6e  ate.** query con
2ecf0 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
2ed00 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2ed10 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 6f  r should be a co
2ed20 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
2ed30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
2ed40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
2ed50 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
2ed60 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2ed70 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
2ed80 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
2ed90 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
2eda0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2edb0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
2edc0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
2edd0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
2ede0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
2edf0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
2ee00 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2ee10 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
2ee20 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2ee30 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 31 7d 20  .**.** {H16211} 
2ee40 54 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61  The first invoca
2ee50 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
2ee60 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2ee70 78 74 28 43 2c 4e 29 5d 20 66 6f 72 0a 2a 2a 20  xt(C,N)] for.** 
2ee80 20 20 20 20 20 20 20 20 20 61 20 70 61 72 74 69           a parti
2ee90 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 20 6f  cular instance o
2eea0 66 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 66  f an aggregate f
2eeb0 75 6e 63 74 69 6f 6e 20 28 66 6f 72 20 61 20 70  unction (for a p
2eec0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 20 20 20  articular.**    
2eed0 20 20 20 20 20 20 63 6f 6e 74 65 78 74 20 43 29        context C)
2eee0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
2eef0 6f 20 61 6c 6c 6f 63 61 74 65 20 4e 20 62 79 74  o allocate N byt
2ef00 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  es of memory,.**
2ef10 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 74            zero t
2ef20 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
2ef30 72 65 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72  return a pointer
2ef40 20 74 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   to the allocate
2ef50 64 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  d memory..**.** 
2ef60 7b 48 31 36 32 31 33 7d 20 49 66 20 61 20 6d 65  {H16213} If a me
2ef70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2ef80 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
2ef90 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
2efa0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
2efb0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d  te_context(C,N)]
2efc0 20 74 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   then the functi
2efd0 6f 6e 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  on returns 0..**
2efe0 0a 2a 2a 20 7b 48 31 36 32 31 35 7d 20 53 65 63  .** {H16215} Sec
2eff0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2f000 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  nt invocations o
2f010 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  f.**          [s
2f020 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2f030 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66  _context(C,N)] f
2f040 6f 72 20 74 68 65 20 73 61 6d 65 20 63 6f 6e 74  or the same cont
2f050 65 78 74 20 70 6f 69 6e 74 65 72 20 43 0a 2a 2a  ext pointer C.**
2f060 20 20 20 20 20 20 20 20 20 20 69 67 6e 6f 72 65            ignore
2f070 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
2f080 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f   and return a po
2f090 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 61 6d  inter to the sam
2f0a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 6c  e.**          bl
2f0b0 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 72 65  ock of memory re
2f0c0 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 66 69  turned by the fi
2f0d0 72 73 74 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a  rst invocation..
2f0e0 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 37 7d 20 54  **.** {H16217} T
2f0f0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
2f100 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ted by [sqlite3_
2f110 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2f120 74 28 43 2c 4e 29 5d 20 69 73 0a 2a 2a 20 20 20  t(C,N)] is.**   
2f130 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63         automatic
2f140 61 6c 6c 79 20 66 72 65 65 64 20 6f 6e 20 74 68  ally freed on th
2f150 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 20 5b  e next call to [
2f160 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2f170 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
2f180 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2f190 65 28 29 5d 20 66 6f 72 20 74 68 65 20 5b 70 72  e()] for the [pr
2f1a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f1b0 5d 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 2a 2a 20  ] containing.** 
2f1c0 20 20 20 20 20 20 20 20 20 74 68 65 20 61 67 67           the agg
2f1d0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
2f1e0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2f1f0 63 6f 6e 74 65 78 74 20 43 2e 0a 2a 2f 0a 76 6f  context C..*/.vo
2f200 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
2f210 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
2f220 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2f230 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
2f240 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
2f250 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
2f260 74 69 6f 6e 73 20 7b 48 31 36 32 34 30 7d 20 3c  tions {H16240} <
2f270 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
2f280 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
2f290 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
2f2a0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2f2b0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
2f2c0 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
2f2d0 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
2f2e0 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
2f2f0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
2f300 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2f310 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
2f320 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2f330 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2f340 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
2f350 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
2f360 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
2f370 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
2f380 66 75 6e 63 74 69 6f 6e 2e 20 7b 45 4e 44 7d 0a  function. {END}.
2f390 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2f3a0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
2f3b0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2f3c0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2f3d0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
2f3e0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2f3f0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2f400 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2f410 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 34 33 7d  :.**.** {H16243}
2f420 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 73   The [sqlite3_us
2f430 65 72 5f 64 61 74 61 28 43 29 5d 20 69 6e 74 65  er_data(C)] inte
2f440 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2f450 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 20  copy of the.**  
2f460 20 20 20 20 20 20 20 20 50 20 70 6f 69 6e 74 65          P pointe
2f470 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  r from the [sqli
2f480 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f490 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  ion(D,X,N,E,P,F,
2f4a0 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  S,L)].**        
2f4b0 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72    or [sqlite3_cr
2f4c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2f4d0 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c 4c 29  D,X,N,E,P,F,S,L)
2f4e0 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a 20 20  ] call that.**  
2f4f0 20 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72          register
2f500 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ed the SQL funct
2f510 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20 77  ion associated w
2f520 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ith [sqlite3_con
2f530 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 76 6f 69 64  text] C..*/.void
2f540 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   *sqlite3_user_d
2f550 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
2f560 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
2f570 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2f580 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20   Connection For 
2f590 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32 35  Functions {H1625
2f5a0 30 7d 20 3c 53 36 30 36 30 30 3e 3c 53 32 30 32  0} <S60600><S202
2f5b0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
2f5c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2f5d0 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
2f5e0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
2f5f0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
2f600 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
2f610 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2f620 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
2f630 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
2f640 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2f650 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
2f660 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2f670 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2f680 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
2f690 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
2f6a0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
2f6b0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
2f6c0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2f6d0 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
2f6e0 2a 20 7b 48 31 36 32 35 33 7d 20 54 68 65 20 5b  * {H16253} The [
2f6f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
2f700 64 62 5f 68 61 6e 64 6c 65 28 43 29 5d 20 69 6e  db_handle(C)] in
2f710 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2f720 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
2f730 20 20 20 20 20 20 20 20 20 20 44 20 70 6f 69 6e            D poin
2f740 74 65 72 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ter from the [sq
2f750 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2f760 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c  ction(D,X,N,E,P,
2f770 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20  F,S,L)].**      
2f780 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f      or [sqlite3_
2f790 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2f7a0 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53 2c  6(D,X,N,E,P,F,S,
2f7b0 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74 0a 2a 2a  L)] call that.**
2f7c0 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
2f7d0 65 72 65 64 20 74 68 65 20 53 51 4c 20 66 75 6e  ered the SQL fun
2f7e0 63 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64  ction associated
2f7f0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 63   with [sqlite3_c
2f800 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f 0a 73 71  ontext] C..*/.sq
2f810 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
2f820 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
2f830 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2f840 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2f850 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
2f860 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b 48 31  xiliary Data {H1
2f870 36 32 37 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  6270} <S20200>.*
2f880 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
2f890 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
2f8a0 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
2f8b0 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
2f8c0 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
2f8d0 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
2f8e0 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
2f8f0 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
2f900 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
2f910 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
2f920 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
2f930 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
2f940 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
2f950 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
2f960 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
2f970 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
2f980 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
2f990 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
2f9a0 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65  . This may.** be
2f9b0 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70   used, for examp
2f9c0 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67  le, to add a reg
2f9d0 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
2f9e0 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a  matching scalar.
2f9f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
2fa00 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
2fa10 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
2fa20 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73   expression is s
2fa30 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
2fa40 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
2fa50 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
2fa60 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
2fa70 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
2fa80 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
2fa90 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
2faa0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
2fab0 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
2fac0 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
2fad0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
2fae0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
2faf0 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
2fb00 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
2fb10 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
2fb20 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
2fb30 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
2fb40 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  ocation..**.** T
2fb50 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
2fb60 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
2fb70 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2fb80 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
2fb90 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
2fba0 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
2fbb0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
2fbc0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68  function with th
2fbd0 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  e Nth argument.*
2fbe0 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61  * value to the a
2fbf0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2fc00 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66 20  ed function. If 
2fc10 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  no metadata has 
2fc20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65  been ever.** bee
2fc30 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74  n set for the Nt
2fc40 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  h argument of th
2fc50 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
2fc60 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
2fc70 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
2fc80 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68  parameter has ch
2fc90 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
2fca0 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
2fcb0 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  t,.** then sqlit
2fcc0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2fcd0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
2fce0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
2fcf0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
2fd00 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
2fd10 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74  ce saves the met
2fd20 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  adata.** pointed
2fd30 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
2fd40 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
2fd50 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
2fd60 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
2fd70 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
2fd80 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2fd90 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65  ction.  Subseque
2fda0 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
2fdb0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2fdc0 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72  ta() might retur
2fdd0 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20  n this data, if 
2fde0 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65  it has.** not be
2fdf0 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  en destroyed..**
2fe00 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55   If it is not NU
2fe10 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
2fe20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
2fe30 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  uctor.** functio
2fe40 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34  n given by the 4
2fe50 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2fe60 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2fe70 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20  ata() on.** the 
2fe80 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68  metadata when th
2fe90 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2fea0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
2feb0 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72  er changes.** or
2fec0 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   when the SQL st
2fed0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65  atement complete
2fee0 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  s, whichever com
2fef0 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
2ff00 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
2ff10 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72  o call the destr
2ff20 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d  uctor and drop m
2ff30 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a  etadata on any.*
2ff40 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61  * parameter of a
2ff50 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61  ny function at a
2ff60 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f 6e  ny time.  The on
2ff70 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20  ly guarantee is 
2ff80 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74  that.** the dest
2ff90 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63  ructor will be c
2ffa0 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65  alled before the
2ffb0 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f   metadata is dro
2ffc0 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 70  pped..**.** In p
2ffd0 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74  ractice, metadat
2ffe0 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62  a is preserved b
2fff0 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20  etween function 
30000 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70  calls for.** exp
30010 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72  ressions that ar
30020 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f  e constant at co
30030 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73  mpile time. This
30040 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61   includes litera
30050 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
30060 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a 2a  SQL variables..*
30070 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
30080 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
30090 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
300a0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
300b0 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
300c0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
300d0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
300e0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 32  S:.**.** {H16272
300f0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 67  } The [sqlite3_g
30100 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 5d  et_auxdata(C,N)]
30110 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30120 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
30130 20 20 20 20 20 20 20 20 20 74 6f 20 6d 65 74 61           to meta
30140 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
30150 77 69 74 68 20 74 68 65 20 4e 74 68 20 70 61 72  with the Nth par
30160 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51  ameter of the SQ
30170 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20  L function.**   
30180 20 20 20 20 20 20 20 77 68 6f 73 65 20 63 6f 6e         whose con
30190 74 65 78 74 20 69 73 20 43 2c 20 6f 72 20 4e 55  text is C, or NU
301a0 4c 4c 20 69 66 20 74 68 65 72 65 20 69 73 20 6e  LL if there is n
301b0 6f 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  o metadata assoc
301c0 69 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  iated.**        
301d0 20 20 77 69 74 68 20 74 68 61 74 20 70 61 72 61    with that para
301e0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  meter..**.** {H1
301f0 36 32 37 34 7d 20 54 68 65 20 5b 73 71 6c 69 74  6274} The [sqlit
30200 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
30210 2c 4e 2c 50 2c 44 29 5d 20 69 6e 74 65 72 66 61  ,N,P,D)] interfa
30220 63 65 20 61 73 73 69 67 6e 73 20 61 20 6d 65 74  ce assigns a met
30230 61 64 61 74 61 0a 2a 2a 20 20 20 20 20 20 20 20  adata.**        
30240 20 20 70 6f 69 6e 74 65 72 20 50 20 74 6f 20 74    pointer P to t
30250 68 65 20 4e 74 68 20 70 61 72 61 6d 65 74 65 72  he Nth parameter
30260 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
30270 74 69 6f 6e 20 77 69 74 68 20 63 6f 6e 74 65 78  tion with contex
30280 74 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  t C..**.** {H162
30290 37 36 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  76} SQLite will 
302a0 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
302b0 75 63 74 6f 72 20 44 20 77 69 74 68 20 61 20 73  uctor D with a s
302c0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ingle argument.*
302d0 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 63 68  *          which
302e0 20 69 73 20 74 68 65 20 6d 65 74 61 64 61 74 61   is the metadata
302f0 20 70 6f 69 6e 74 65 72 20 50 20 66 6f 6c 6c 6f   pointer P follo
30300 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  wing a call to.*
30310 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
30320 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
30330 43 2c 4e 2c 50 2c 44 29 5d 20 77 68 65 6e 20 53  C,N,P,D)] when S
30340 51 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20  QLite ceases to 
30350 68 6f 6c 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  hold.**         
30360 20 74 68 65 20 6d 65 74 61 64 61 74 61 2e 0a 2a   the metadata..*
30370 2a 0a 2a 2a 20 7b 48 31 36 32 37 37 7d 20 53 51  *.** {H16277} SQ
30380 4c 69 74 65 20 63 65 61 73 65 73 20 74 6f 20 68  Lite ceases to h
30390 6f 6c 64 20 6d 65 74 61 64 61 74 61 20 66 6f 72  old metadata for
303a0 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
303b0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
303c0 20 20 20 20 20 20 20 77 68 65 6e 20 74 68 65 20         when the 
303d0 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 70 61  value of that pa
303e0 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2e  rameter changes.
303f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37 38 7d 20  .**.** {H16278} 
30400 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 65  When [sqlite3_se
30410 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
30420 44 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  D)] is invoked, 
30430 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
30440 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 63 61  *          is ca
30450 6c 6c 65 64 20 66 6f 72 20 61 6e 79 20 70 72 69  lled for any pri
30460 6f 72 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  or metadata asso
30470 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
30480 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  same function.**
30490 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65 78            contex
304a0 74 20 43 20 61 6e 64 20 70 61 72 61 6d 65 74 65  t C and paramete
304b0 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  r N..**.** {H162
304c0 37 39 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  79} SQLite will 
304d0 63 61 6c 6c 20 64 65 73 74 72 75 63 74 6f 72 73  call destructors
304e0 20 66 6f 72 20 61 6e 79 20 6d 65 74 61 64 61 74   for any metadat
304f0 61 20 69 74 20 69 73 20 68 6f 6c 64 69 6e 67 0a  a it is holding.
30500 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 61  **          in a
30510 20 70 61 72 74 69 63 75 6c 61 72 20 5b 70 72 65   particular [pre
30520 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30530 20 53 20 77 68 65 6e 20 65 69 74 68 65 72 0a 2a   S when either.*
30540 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
30550 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 6f 72  te3_reset(S)] or
30560 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
30570 7a 65 28 53 29 5d 20 69 73 20 63 61 6c 6c 65 64  ze(S)] is called
30580 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
30590 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
305a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
305b0 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71   int N);.void sq
305c0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
305d0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
305e0 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a  t*, int N, void*
305f0 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a  , void (*)(void*
30600 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ));.../*.** CAPI
30610 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20  3REF: Constants 
30620 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c  Defining Special
30630 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61   Destructor Beha
30640 76 69 6f 72 20 7b 48 31 30 32 38 30 7d 20 3c 53  vior {H10280} <S
30650 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  30100>.**.** The
30660 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76  se are special v
30670 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65  alues for the de
30680 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73  structor that is
30690 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
306a0 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d  e.** final argum
306b0 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  ent to routines 
306c0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  like [sqlite3_re
306d0 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49  sult_blob()].  I
306e0 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
306f0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
30700 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
30710 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
30720 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
30730 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
30740 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
30750 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
30760 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
30770 65 73 74 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a  estroyed.  The.*
30780 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  * SQLITE_TRANSIE
30790 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74  NT value means t
307a0 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
307b0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e  will likely chan
307c0 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61  ge in.** the nea
307d0 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61  r future and tha
307e0 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20  t SQLite should 
307f0 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69  make its own pri
30800 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  vate copy of.** 
30810 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f  the content befo
30820 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
30830 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20  .** The typedef 
30840 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20  is necessary to 
30850 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62  work around prob
30860 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a  lems in certain.
30870 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73  ** C++ compilers
30880 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32  .  See ticket #2
30890 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  191..*/.typedef 
308a0 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64  void (*sqlite3_d
308b0 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28  estructor_type)(
308c0 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20  void*);.#define 
308d0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20  SQLITE_STATIC   
308e0 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
308f0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a  tructor_type)0).
30900 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
30910 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c  RANSIENT   ((sql
30920 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
30930 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20  type)-1)../*.** 
30940 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e  CAPI3REF: Settin
30950 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20  g The Result Of 
30960 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  An SQL Function 
30970 7b 48 31 36 34 30 30 7d 20 3c 53 32 30 32 30 30  {H16400} <S20200
30980 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
30990 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
309a0 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
309b0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
309c0 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
309d0 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
309e0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
309f0 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
30a00 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30a10 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
30a20 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30a30 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
30a40 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
30a50 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
30a60 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
30a70 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
30a80 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
30a90 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
30aa0 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
30ab0 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
30ac0 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
30ad0 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
30ae0 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
30af0 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
30b00 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
30b10 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
30b20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
30b30 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
30b40 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
30b50 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  _blob() interfac
30b60 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
30b70 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
30b80 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
30b90 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
30ba0 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63  the BLOB whose c
30bb0 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65  ontent is pointe
30bc0 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73  d.** to by the s
30bd0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
30be0 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62  and which is N b
30bf0 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20  ytes long where 
30c00 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  N is the.** thir
30c10 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
30c20 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
30c30 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
30c40 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20   interfaces set 
30c50 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
30c60 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
30c70 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
30c80 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63  n to be a BLOB c
30c90 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65  ontaining all ze
30ca0 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20  ro.** bytes and 
30cb0 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c  N bytes in size,
30cc0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
30cd0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64  value of the 2nd
30ce0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
30cf0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
30d00 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e  sult_double() in
30d10 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
30d20 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
30d30 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
30d40 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
30d50 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67  to be a floating
30d60 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65   point value spe
30d70 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73  cified.** by its
30d80 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
30d90 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
30da0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
30db0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
30dc0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
30dd0 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
30de0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
30df0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
30e00 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
30e10 6f 6e 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  on..** SQLite us
30e20 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f  es the string po
30e30 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a  inted to by the.
30e40 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ** 2nd parameter
30e50 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75   of sqlite3_resu
30e60 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
30e70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30e80 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65  or16().** as the
30e90 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
30ea0 72 20 6d 65 73 73 61 67 65 2e 20 20 53 51 4c 69  r message.  SQLi
30eb0 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
30ec0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
30ed0 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  ge string from s
30ee0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
30ef0 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20  ror() as UTF-8. 
30f00 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
30f10 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
30f20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
30f30 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
30f40 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
30f50 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
30f60 20 20 49 66 20 74 68 65 20 74 68 69 72 64 20 70    If the third p
30f70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
30f80 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30f90 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
30fa0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
30fb0 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
30fc0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
30fd0 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
30fe0 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
30ff0 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
31000 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
31010 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  cter..** If the 
31020 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
31030 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
31040 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
31050 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31060 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
31070 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
31080 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
31090 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
310a0 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
310b0 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
310c0 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
310d0 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54  or message..** T
310e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
310f0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
31100 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31110 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
31120 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
31130 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
31140 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
31150 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
31160 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
31170 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
31180 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
31190 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
311a0 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
311b0 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
311c0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65  out harm..** The
311d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
311e0 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
311f0 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
31200 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
31210 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
31220 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
31230 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
31240 66 75 6e 63 74 69 6f 6e 2e 20 20 42 79 20 64 65  function.  By de
31250 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72  fault,.** the er
31260 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49  ror code is SQLI
31270 54 45 5f 45 52 52 4f 52 2e 20 20 41 20 73 75 62  TE_ERROR.  A sub
31280 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
31290 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
312a0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
312b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
312c0 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
312d0 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
312e0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
312f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
31300 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69  esult_toobig() i
31310 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
31320 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
31330 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
31340 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
31350 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
31360 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  to long to repre
31370 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  sent..**.** The 
31380 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
31390 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
313a0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
313b0 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72  o throw an error
313c0 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74  .** indicating t
313d0 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  hat a memory all
313e0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
313f0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
31400 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
31410 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
31420 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
31430 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
31440 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
31450 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
31460 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
31470 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
31480 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
31490 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
314a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
314b0 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  int64() interfac
314c0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
314d0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
314e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
314f0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
31500 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20  o be the 64-bit 
31510 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
31520 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
31530 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
31540 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  t..**.** The sql
31550 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
31560 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
31570 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
31580 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
31590 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
315a0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
315b0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
315c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
315d0 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
315e0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a  esult_text16(),.
315f0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
31600 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e  t_text16le(), an
31610 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
31620 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65  _text16be() inte
31630 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68  rfaces.** set th
31640 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
31650 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
31660 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
31670 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65  on to be.** a te
31680 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20  xt string which 
31690 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
316a0 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20  s UTF-8, UTF-16 
316b0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
316c0 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  r,.** UTF-16 lit
316d0 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle endian, or U
316e0 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e  TF-16 big endian
316f0 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
31700 2a 2a 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  ** SQLite takes 
31710 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20  the text result 
31720 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61  from the applica
31730 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  tion from.** the
31740 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
31750 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  f the sqlite3_re
31760 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
31770 66 61 63 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65  faces..** If the
31780 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
31790 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
317a0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
317b0 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61  faces.** is nega
317c0 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74  tive, then SQLit
317d0 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74  e takes result t
317e0 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  ext from the 2nd
317f0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68   parameter.** th
31800 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
31810 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
31820 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
31830 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
31840 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31850 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
31860 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
31870 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
31880 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
31890 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
318a0 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
318b0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
318c0 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
318d0 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
318e0 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
318f0 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a  nction result..*
31900 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72  * If the 4th par
31910 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
31920 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31930 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
31940 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
31950 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e  lt_blob is a non
31960 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
31970 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73  hen SQLite calls
31980 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f   that.** functio
31990 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63  n as the destruc
319a0 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20  tor on the text 
319b0 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77  or BLOB result w
319c0 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69  hen it has.** fi
319d0 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
319e0 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20  t result..** If 
319f0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
31a00 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
31a10 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
31a20 74 65 72 66 61 63 65 73 20 6f 72 0a 2a 2a 20 73  terfaces or.** s
31a30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
31a40 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
31a50 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
31a60 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53  E_STATIC, then S
31a70 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73  QLite.** assumes
31a80 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f   that the text o
31a90 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73  r BLOB result is
31aa0 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61   in constant spa
31ab0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a  ce and does not.
31ac0 2a 2a 20 63 6f 70 79 20 74 68 65 20 69 74 20 6f  ** copy the it o
31ad0 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
31ae0 74 6f 72 20 77 68 65 6e 20 69 74 20 68 61 73 20  tor when it has 
31af0 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
31b00 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  hat result..** I
31b10 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
31b20 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
31b30 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
31b40 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
31b50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31b60 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
31b70 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
31b80 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
31b90 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
31ba0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
31bb0 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
31bc0 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
31bd0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
31be0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
31bf0 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
31c00 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
31c10 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
31c20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
31c30 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
31c40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
31c50 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
31c60 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
31c70 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
31c80 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
31c90 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
31ca0 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
31cb0 61 6d 65 74 65 72 2e 20 20 54 68 65 0a 2a 2a 20  ameter.  The.** 
31cc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
31cd0 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
31ce0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
31cf0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
31d00 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
31d10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
31d20 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e  ue] specified in
31d30 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d   the parameter m
31d40 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  ay change or.** 
31d50 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61  be deallocated a
31d60 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73  fter sqlite3_res
31d70 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75  ult_value() retu
31d80 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d  rns without harm
31d90 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65 63 74 65  ..** A [protecte
31da0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
31db0 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61   object may alwa
31dc0 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65  ys be used where
31dd0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
31de0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
31df0 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71  e] object is req
31e00 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72  uired, so either
31e10 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c  .** kind of [sql
31e20 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
31e30 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77  ct can be used w
31e40 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61  ith this interfa
31e50 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ce..**.** If the
31e60 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
31e70 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68  called from with
31e80 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74  in the different
31e90 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20   thread.** than 
31ea0 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69  the one containi
31eb0 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ng the applicati
31ec0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
31ed0 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65  ion that receive
31ee0 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  d.** the [sqlite
31ef0 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74  3_context] point
31f00 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  er, the results 
31f10 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
31f20 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
31f30 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 33 7d 20  .**.** {H16403} 
31f40 54 68 65 20 64 65 66 61 75 6c 74 20 72 65 74 75  The default retu
31f50 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e  rn value from an
31f60 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  y SQL function i
31f70 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  s NULL..**.** {H
31f80 31 36 34 30 36 7d 20 54 68 65 20 5b 73 71 6c 69  16406} The [sqli
31f90 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
31fa0 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
31fb0 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
31fc0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
31fd0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
31fe0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 20 42  tion C to be a B
31ff0 4c 4f 42 20 74 68 61 74 20 69 73 20 4e 20 62 79  LOB that is N by
32000 74 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tes.**          
32010 69 6e 20 6c 65 6e 67 74 68 20 61 6e 64 20 77 69  in length and wi
32020 74 68 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  th content point
32030 65 64 20 74 6f 20 62 79 20 56 2e 0a 2a 2a 0a 2a  ed to by V..**.*
32040 2a 20 7b 48 31 36 34 30 39 7d 20 54 68 65 20 5b  * {H16409} The [
32050 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
32060 6f 75 62 6c 65 28 43 2c 56 29 5d 20 69 6e 74 65  ouble(C,V)] inte
32070 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
32080 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  e.**          re
32090 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75  turn value of fu
320a0 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74  nction C to be t
320b0 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
320c0 74 20 76 61 6c 75 65 20 56 2e 0a 2a 2a 0a 2a 2a  t value V..**.**
320d0 20 7b 48 31 36 34 31 32 7d 20 54 68 65 20 5b 73   {H16412} The [s
320e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
320f0 72 6f 72 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65  ror(C,V,N)] inte
32100 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
32110 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
32120 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 66 75       value of fu
32130 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61  nction C to be a
32140 6e 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68  n exception with
32150 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20   error code.**  
32160 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
32170 45 52 52 4f 52 5d 20 61 6e 64 20 61 20 55 54 46  ERROR] and a UTF
32180 2d 38 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  -8 error message
32190 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 56 20 75   copied from V u
321a0 70 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  p to the.**     
321b0 20 20 20 20 20 66 69 72 73 74 20 7a 65 72 6f 20       first zero 
321c0 62 79 74 65 20 6f 72 20 75 6e 74 69 6c 20 4e 20  byte or until N 
321d0 62 79 74 65 73 20 61 72 65 20 72 65 61 64 20 69  bytes are read i
321e0 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2e  f N is positive.
321f0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 35 7d 20  .**.** {H16415} 
32200 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
32210 75 6c 74 5f 65 72 72 6f 72 31 36 28 43 2c 56 2c  ult_error16(C,V,
32220 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  N)] interface ch
32230 61 6e 67 65 73 20 74 68 65 20 72 65 74 75 72 6e  anges the return
32240 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c  .**          val
32250 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
32260 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70 74   to be an except
32270 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20 63  ion with error c
32280 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ode.**          
32290 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61  [SQLITE_ERROR] a
322a0 6e 64 20 61 20 55 54 46 2d 31 36 20 6e 61 74 69  nd a UTF-16 nati
322b0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 65 72  ve byte order er
322c0 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 20  ror message.**  
322d0 20 20 20 20 20 20 20 20 63 6f 70 69 65 64 20 66          copied f
322e0 72 6f 6d 20 56 20 75 70 20 74 6f 20 74 68 65 20  rom V up to the 
322f0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
32300 6e 61 74 6f 72 20 6f 72 20 75 6e 74 69 6c 20 4e  nator or until N
32310 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20 20 20   bytes.**       
32320 20 20 20 61 72 65 20 72 65 61 64 20 69 66 20 4e     are read if N
32330 20 69 73 20 70 6f 73 69 74 69 76 65 2e 0a 2a 2a   is positive..**
32340 0a 2a 2a 20 7b 48 31 36 34 31 38 7d 20 54 68 65  .** {H16418} The
32350 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
32360 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 43 29  _error_toobig(C)
32370 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
32380 67 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a  ges the return.*
32390 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65  *          value
323a0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
323b0 20 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65   C to be an exce
323c0 70 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72  ption with error
323d0 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20 20 20 20   code.**        
323e0 20 20 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47    [SQLITE_TOOBIG
323f0 5d 20 61 6e 64 20 61 6e 20 61 70 70 72 6f 70 72  ] and an appropr
32400 69 61 74 65 20 65 72 72 6f 72 20 6d 65 73 73 61  iate error messa
32410 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32  ge..**.** {H1642
32420 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
32430 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
32440 65 6d 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  em(C)] interface
32450 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
32460 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
32470 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e  value of the fun
32480 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
32490 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
324a0 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
324b0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4e         [SQLITE_N
324c0 4f 4d 45 4d 5d 20 61 6e 64 20 61 6e 20 61 70 70  OMEM] and an app
324d0 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d  ropriate error m
324e0 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  essage..**.** {H
324f0 31 36 34 32 34 7d 20 54 68 65 20 5b 73 71 6c 69  16424} The [sqli
32500 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
32510 5f 63 6f 64 65 28 43 2c 45 29 5d 20 69 6e 74 65  _code(C,E)] inte
32520 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
32530 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
32540 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
32550 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  e function C to 
32560 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
32570 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 20  with error code 
32580 45 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 54  E..**          T
32590 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
325a0 20 74 65 78 74 20 69 73 20 75 6e 63 68 61 6e 67   text is unchang
325b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 32  ed..**.** {H1642
325c0 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  7} The [sqlite3_
325d0 72 65 73 75 6c 74 5f 69 6e 74 28 43 2c 56 29 5d  result_int(C,V)]
325e0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
325f0 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
32600 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
32610 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
32620 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 69   be the 32-bit i
32630 6e 74 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a  nteger value V..
32640 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 30 7d 20 54  **.** {H16430} T
32650 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
32660 6c 74 5f 69 6e 74 36 34 28 43 2c 56 29 5d 20 69  lt_int64(C,V)] i
32670 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
32680 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
32690 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
326a0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
326b0 65 20 74 68 65 20 36 34 2d 62 69 74 20 69 6e 74  e the 64-bit int
326c0 65 67 65 72 20 76 61 6c 75 65 20 56 2e 0a 2a 2a  eger value V..**
326d0 0a 2a 2a 20 7b 48 31 36 34 33 33 7d 20 54 68 65  .** {H16433} The
326e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
326f0 5f 6e 75 6c 6c 28 43 29 5d 20 69 6e 74 65 72 66  _null(C)] interf
32700 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
32710 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
32720 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
32730 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 4e 55 4c  tion C to be NUL
32740 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 36  L..**.** {H16436
32750 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
32760 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e  esult_text(C,V,N
32770 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
32780 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
32790 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
327a0 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
327b0 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d  C to be the UTF-
327c0 38 20 73 74 72 69 6e 67 0a 2a 2a 20 20 20 20 20  8 string.**     
327d0 20 20 20 20 20 56 20 75 70 20 74 6f 20 74 68 65       V up to the
327e0 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
327f0 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20   is negative.** 
32800 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
32810 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66  first N bytes of
32820 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e   V if N is non-n
32830 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
32840 48 31 36 34 33 39 7d 20 54 68 65 20 5b 73 71 6c  H16439} The [sql
32850 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32860 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74  16(C,V,N,D)] int
32870 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
32880 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
32890 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
328a0 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
328b0 74 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76  the UTF-16 nativ
328c0 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a 2a 20  e byte order.** 
328d0 20 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20           string 
328e0 56 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  V up to the firs
328f0 74 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e  t zero if N is n
32900 65 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20  egative.**      
32910 20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74      or the first
32920 20 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66   N bytes of V if
32930 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69   N is non-negati
32940 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34  ve..**.** {H1644
32950 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
32960 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
32970 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
32980 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
32990 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
329a0 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
329b0 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
329c0 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69   UTF-16 big-endi
329d0 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  an.**          s
329e0 74 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68  tring V up to th
329f0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20  e first zero if 
32a00 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  N is negative.**
32a10 20 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65            or the
32a20 20 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f   first N bytes o
32a30 72 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d  r V if N is non-
32a40 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20  negative..**.** 
32a50 7b 48 31 36 34 34 35 7d 20 54 68 65 20 5b 73 71  {H16445} The [sq
32a60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32a70 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16le(C,V,N,D)] 
32a80 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65  interface change
32a90 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
32aa0 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f    return value o
32ab0 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  f function C to 
32ac0 62 65 20 74 68 65 20 55 54 46 2d 31 36 20 6c 69  be the UTF-16 li
32ad0 74 74 6c 65 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20  ttle-endian.**  
32ae0 20 20 20 20 20 20 20 20 73 74 72 69 6e 67 20 56          string V
32af0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
32b00 20 7a 65 72 6f 20 69 66 20 4e 20 69 73 20 6e 65   zero if N is ne
32b10 67 61 74 69 76 65 0a 2a 2a 20 20 20 20 20 20 20  gative.**       
32b20 20 20 20 6f 72 20 74 68 65 20 66 69 72 73 74 20     or the first 
32b30 4e 20 62 79 74 65 73 20 6f 66 20 56 20 69 66 20  N bytes of V if 
32b40 4e 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  N is non-negativ
32b50 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 34 38  e..**.** {H16448
32b60 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
32b70 65 73 75 6c 74 5f 76 61 6c 75 65 28 43 2c 56 29  esult_value(C,V)
32b80 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
32b90 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
32ba0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
32bb0 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
32bc0 6f 20 62 65 20 74 68 65 20 5b 75 6e 70 72 6f 74  o be the [unprot
32bd0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32be0 6c 75 65 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  lue].**         
32bf0 20 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a   object V..**.**
32c00 20 7b 48 31 36 34 35 31 7d 20 54 68 65 20 5b 73   {H16451} The [s
32c10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
32c20 72 6f 62 6c 6f 62 28 43 2c 4e 29 5d 20 69 6e 74  roblob(C,N)] int
32c30 65 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74  erface changes t
32c40 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  he.**          r
32c50 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 66  eturn value of f
32c60 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20  unction C to be 
32c70 61 6e 20 4e 2d 62 79 74 65 20 42 4c 4f 42 20 6f  an N-byte BLOB o
32c80 66 20 61 6c 6c 20 7a 65 72 6f 73 2e 0a 2a 2a 0a  f all zeros..**.
32c90 2a 2a 20 7b 48 31 36 34 35 34 7d 20 54 68 65 20  ** {H16454} The 
32ca0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
32cb0 65 72 72 6f 72 28 29 5d 20 61 6e 64 20 5b 73 71  error()] and [sq
32cc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32cd0 6f 72 31 36 28 29 5d 0a 2a 2a 20 20 20 20 20 20  or16()].**      
32ce0 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 20 6d      interfaces m
32cf0 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ake a copy of th
32d00 65 69 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67  eir error messag
32d10 65 20 73 74 72 69 6e 67 73 20 62 65 66 6f 72 65  e strings before
32d20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74  .**          ret
32d30 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48  urning..**.** {H
32d40 31 36 34 35 37 7d 20 49 66 20 74 68 65 20 44 20  16457} If the D 
32d50 64 65 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d  destructor param
32d60 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
32d70 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56  _result_blob(C,V
32d80 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20  ,N,D)],.**      
32d90 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73      [sqlite3_res
32da0 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44  ult_text(C,V,N,D
32db0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  )], [sqlite3_res
32dc0 75 6c 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e  ult_text16(C,V,N
32dd0 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
32de0 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
32df0 74 5f 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e  t_text16be(C,V,N
32e00 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  ,D)], or.**     
32e10 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
32e20 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c  sult_text16le(C,
32e30 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68 65 20 63  V,N,D)] is the c
32e40 6f 6e 73 74 61 6e 74 20 5b 53 51 4c 49 54 45 5f  onstant [SQLITE_
32e50 53 54 41 54 49 43 5d 0a 2a 2a 20 20 20 20 20 20  STATIC].**      
32e60 20 20 20 20 74 68 65 6e 20 6e 6f 20 64 65 73 74      then no dest
32e70 72 75 63 74 6f 72 20 69 73 20 65 76 65 72 20 63  ructor is ever c
32e80 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 70 6f 69  alled on the poi
32e90 6e 74 65 72 20 56 20 61 6e 64 20 53 51 4c 69 74  nter V and SQLit
32ea0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73  e.**          as
32eb0 73 75 6d 65 73 20 74 68 61 74 20 56 20 69 73 20  sumes that V is 
32ec0 69 6d 6d 75 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  immutable..**.**
32ed0 20 7b 48 31 36 34 36 30 7d 20 49 66 20 74 68 65   {H16460} If the
32ee0 20 44 20 64 65 73 74 72 75 63 74 6f 72 20 70 61   D destructor pa
32ef0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
32f00 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
32f10 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
32f20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
32f30 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c 56 2c  result_text(C,V,
32f40 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  N,D)], [sqlite3_
32f50 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 43 2c  result_text16(C,
32f60 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20  V,N,D)],.**     
32f70 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65       [sqlite3_re
32f80 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 43 2c  sult_text16be(C,
32f90 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,N,D)], or.**  
32fa0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
32fb0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
32fc0 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20 74 68  (C,V,N,D)] is th
32fd0 65 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 20 20  e constant.**   
32fe0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54         [SQLITE_T
32ff0 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 20 74  RANSIENT] then t
33000 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  he interfaces ma
33010 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
33020 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f  e.**          co
33030 6e 74 65 6e 74 20 6f 66 20 56 20 61 6e 64 20 72  ntent of V and r
33040 65 74 61 69 6e 73 20 74 68 65 20 63 6f 70 79 2e  etains the copy.
33050 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 33 7d 20  .**.** {H16463} 
33060 49 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63  If the D destruc
33070 74 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f  tor parameter to
33080 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
33090 5f 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c  _blob(C,V,N,D)],
330a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
330b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
330c0 74 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71  t(C,V,N,D)], [sq
330d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
330e0 74 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a  t16(C,V,N,D)],.*
330f0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
33100 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
33110 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f  6be(C,V,N,D)], o
33120 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
33130 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33140 78 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d  xt16le(C,V,N,D)]
33150 20 69 73 20 73 6f 6d 65 20 76 61 6c 75 65 20 6f   is some value o
33160 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20 20 20  ther than.**    
33170 20 20 20 20 20 20 74 68 65 20 63 6f 6e 73 74 61        the consta
33180 6e 74 73 20 5b 53 51 4c 49 54 45 5f 53 54 41 54  nts [SQLITE_STAT
33190 49 43 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  IC] and [SQLITE_
331a0 54 52 41 4e 53 49 45 4e 54 5d 20 74 68 65 6e 0a  TRANSIENT] then.
331b0 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69  **          SQLi
331c0 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
331d0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 44 20  he destructor D 
331e0 77 69 74 68 20 56 20 61 73 20 69 74 73 20 6f 6e  with V as its on
331f0 6c 79 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 20  ly argument.**  
33200 20 20 20 20 20 20 20 20 77 68 65 6e 20 69 74 20          when it 
33210 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
33220 68 20 74 68 65 20 56 20 76 61 6c 75 65 2e 0a 2a  h the V value..*
33230 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
33240 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
33250 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
33260 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
33270 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
33280 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33290 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
332a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
332b0 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
332c0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
332d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
332e0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
332f0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
33300 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
33310 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33320 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
33330 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
33340 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
33350 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
33360 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
33370 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33380 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
33390 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
333a0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
333b0 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
333c0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
333d0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
333e0 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
333f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
33400 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
33410 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
33420 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33430 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
33440 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33450 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
33460 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
33470 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33480 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
33490 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
334a0 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
334b0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
334c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
334d0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
334e0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
334f0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
33500 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
33510 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
33520 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
33530 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
33540 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
33550 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
33560 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
33570 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
33580 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
33590 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
335a0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
335b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
335c0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
335d0 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
335e0 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
335f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
33600 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
33610 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
33620 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33630 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
33640 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 20  ating Sequences 
33650 7b 48 31 36 36 30 30 7d 20 3c 53 32 30 33 30 30  {H16600} <S20300
33660 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  >.**.** These fu
33670 6e 63 74 69 6f 6e 73 20 61 72 65 20 75 73 65 64  nctions are used
33680 20 74 6f 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c   to add new coll
33690 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
336a0 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  to the.** [datab
336b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
336c0 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65  specified as the
336d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
336e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20  .**.** The name 
336f0 6f 66 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61  of the new colla
33700 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73  tion sequence is
33710 20 73 70 65 63 69 66 69 65 64 20 61 73 20 61 20   specified as a 
33720 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
33730 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
33740 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
33750 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
33760 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
33770 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
33780 20 73 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69   string for sqli
33790 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
337a0 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c  tion16(). In all
337b0 20 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61   cases.** the na
337c0 6d 65 20 69 73 20 70 61 73 73 65 64 20 61 73 20  me is passed as 
337d0 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
337e0 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
337f0 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72  .** The third ar
33800 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e  gument may be on
33810 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e  e of the constan
33820 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ts [SQLITE_UTF8]
33830 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  ,.** [SQLITE_UTF
33840 31 36 4c 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45  16LE] or [SQLITE
33850 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63  _UTF16BE], indic
33860 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 75  ating that the u
33870 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ser-supplied.** 
33880 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20  routine expects 
33890 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69  to be passed poi
338a0 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
338b0 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55   encoded using U
338c0 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  TF-8,.** UTF-16 
338d0 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f  little-endian, o
338e0 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64  r UTF-16 big-end
338f0 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
33900 79 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  y. The.** third 
33910 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61  argument might a
33920 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55  lso be [SQLITE_U
33930 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 74 6f  TF16_ALIGNED] to
33940 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 0a 2a   indicate that.*
33950 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78  * the routine ex
33960 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74  pects pointers t
33970 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c  o 16-bit word al
33980 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  igned strings.**
33990 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68   of UTF-16 in th
339a0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
339b0 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
339c0 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  computer..**.** 
339d0 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
339e0 20 75 73 65 72 20 73 75 70 70 6c 69 65 64 20 72   user supplied r
339f0 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70  outine must be p
33a00 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 66  assed as the fif
33a10 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  th.** argument. 
33a20 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20   If it is NULL, 
33a30 74 68 69 73 20 69 73 20 74 68 65 20 73 61 6d 65  this is the same
33a40 20 61 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65   as deleting the
33a50 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
33a60 71 75 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20  quence (so that 
33a70 53 51 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61  SQLite cannot ca
33a80 6c 6c 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a  ll it anymore)..
33a90 2a 2a 20 45 61 63 68 20 74 69 6d 65 20 74 68 65  ** Each time the
33aa0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70   application sup
33ab0 70 6c 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  plied function i
33ac0 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73  s invoked, it is
33ad0 20 70 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74   passed.** as it
33ae0 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
33af0 72 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  r a copy of the 
33b00 76 6f 69 64 2a 20 70 61 73 73 65 64 20 61 73 20  void* passed as 
33b10 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
33b20 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
33b30 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33b40 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  on() or sqlite3_
33b50 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
33b60 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  16()..**.** The 
33b70 72 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65  remaining argume
33b80 6e 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69  nts to the appli
33b90 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20  cation-supplied 
33ba0 72 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20  routine are two 
33bb0 73 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68  strings,.** each
33bc0 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
33bd0 61 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29  a (length, data)
33be0 20 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65   pair and encode
33bf0 64 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e  d in the encodin
33c00 67 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61  g.** that was pa
33c10 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
33c20 64 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20  d argument when 
33c30 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  the collation se
33c40 71 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65  quence was.** re
33c50 67 69 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20  gistered. {END} 
33c60 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
33c70 20 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69   defined collati
33c80 6f 6e 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c  on routine shoul
33c90 64 0a 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61  d.** return nega
33ca0 74 69 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f  tive, zero or po
33cb0 73 69 74 69 76 65 20 69 66 20 74 68 65 20 66 69  sitive if the fi
33cc0 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65  rst string is le
33cd0 73 73 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61  ss than,.** equa
33ce0 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
33cf0 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
33d00 20 73 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53   string. i.e. (S
33d10 54 52 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32  TRING1 - STRING2
33d20 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
33d30 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33d40 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73  ation_v2() works
33d50 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72   like sqlite3_cr
33d60 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
33d70 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
33d80 69 74 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72  it takes an extr
33d90 61 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  a argument which
33da0 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
33db0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c   for.** the coll
33dc0 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74  ation.  The dest
33dd0 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
33de0 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   when the collat
33df0 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f  ion is.** destro
33e00 79 65 64 20 61 6e 64 20 69 73 20 70 61 73 73 65  yed and is passe
33e10 64 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  d a copy of the 
33e20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
33e30 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a   void* pointer.*
33e40 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
33e50 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
33e60 6e 5f 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61  n_v2()..** Colla
33e70 74 69 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f  tions are destro
33e80 79 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72  yed when they ar
33e90 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
33ea0 6c 61 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74  later calls to t
33eb0 68 65 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20  he.** collation 
33ec0 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  creation functio
33ed0 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b  ns or when the [
33ee0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33ef0 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a  ion] is closed.*
33f00 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
33f10 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
33f20 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
33f30 2a 2a 20 7b 48 31 36 36 30 33 7d 20 41 20 73 75  ** {H16603} A su
33f40 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
33f50 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
33f60 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33f70 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
33f80 58 2c 45 2c 50 2c 46 2c 44 29 5d 20 69 6e 74 65  X,E,P,F,D)] inte
33f90 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20  rface.**        
33fa0 20 20 72 65 67 69 73 74 65 72 73 20 66 75 6e 63    registers func
33fb0 74 69 6f 6e 20 46 20 61 73 20 74 68 65 20 63 6f  tion F as the co
33fc0 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f  mparison functio
33fd0 6e 20 75 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20  n used to.**    
33fe0 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74 20        implement 
33ff0 63 6f 6c 6c 61 74 69 6f 6e 20 58 20 6f 6e 20 74  collation X on t
34000 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
34010 6e 65 63 74 69 6f 6e 5d 20 42 20 66 6f 72 0a 2a  nection] B for.*
34020 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61 62  *          datab
34030 61 73 65 73 20 68 61 76 69 6e 67 20 65 6e 63 6f  ases having enco
34040 64 69 6e 67 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ding E..**.** {H
34050 31 36 36 30 34 7d 20 53 51 4c 69 74 65 20 75 6e  16604} SQLite un
34060 64 65 72 73 74 61 6e 64 73 20 74 68 65 20 58 20  derstands the X 
34070 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
34080 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
34090 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
340a0 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c  on_v2(B,X,E,P,F,
340b0 44 29 5d 20 61 73 20 61 20 7a 65 72 6f 2d 74 65  D)] as a zero-te
340c0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20  rminated.**     
340d0 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69 6e       UTF-8 strin
340e0 67 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  g in which case 
340f0 69 73 20 69 67 6e 6f 72 65 64 20 66 6f 72 20 41  is ignored for A
34100 53 43 49 49 20 63 68 61 72 61 63 74 65 72 73 20  SCII characters 
34110 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
34120 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74 20 66  is significant f
34130 6f 72 20 6e 6f 6e 2d 41 53 43 49 49 20 63 68 61  or non-ASCII cha
34140 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b  racters..**.** {
34150 48 31 36 36 30 36 7d 20 53 75 63 63 65 73 73 69  H16606} Successi
34160 76 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  ve calls to [sql
34170 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
34180 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50  ation_v2(B,X,E,P
34190 2c 46 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,F,D)].**       
341a0 20 20 20 77 69 74 68 20 74 68 65 20 73 61 6d 65     with the same
341b0 20 76 61 6c 75 65 73 20 66 6f 72 20 42 2c 20 58   values for B, X
341c0 2c 20 61 6e 64 20 45 2c 20 6f 76 65 72 72 69 64  , and E, overrid
341d0 65 20 70 72 69 6f 72 20 76 61 6c 75 65 73 0a 2a  e prior values.*
341e0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 50 2c  *          of P,
341f0 20 46 2c 20 61 6e 64 20 44 2e 0a 2a 2a 0a 2a 2a   F, and D..**.**
34200 20 7b 48 31 36 36 30 39 7d 20 49 66 20 74 68 65   {H16609} If the
34210 20 64 65 73 74 72 75 63 74 6f 72 20 44 20 69 6e   destructor D in
34220 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34230 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
34240 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20  X,E,P,F,D)].**  
34250 20 20 20 20 20 20 20 20 69 73 20 6e 6f 74 20 4e          is not N
34260 55 4c 4c 20 74 68 65 6e 20 69 74 20 69 73 20 63  ULL then it is c
34270 61 6c 6c 65 64 20 77 69 74 68 20 61 72 67 75 6d  alled with argum
34280 65 6e 74 20 50 20 77 68 65 6e 20 74 68 65 0a 2a  ent P when the.*
34290 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
342a0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
342b0 20 64 72 6f 70 70 65 64 20 62 79 20 53 51 4c 69   dropped by SQLi
342c0 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 31  te..**.** {H1661
342d0 32 7d 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66  2} A collating f
342e0 75 6e 63 74 69 6f 6e 20 69 73 20 64 72 6f 70 70  unction is dropp
342f0 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 6f 76  ed when it is ov
34300 65 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  erloaded..**.** 
34310 7b 48 31 36 36 31 35 7d 20 41 20 63 6f 6c 6c 61  {H16615} A colla
34320 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
34330 20 64 72 6f 70 70 65 64 20 77 68 65 6e 20 74 68   dropped when th
34340 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
34350 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
34360 20 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e    is closed usin
34370 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  g [sqlite3_close
34380 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36  ()]..**.** {H166
34390 31 38 7d 20 54 68 65 20 70 6f 69 6e 74 65 72 20  18} The pointer 
343a0 50 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63 72  P in [sqlite3_cr
343b0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
343c0 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a  2(B,X,E,P,F,D)].
343d0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 70  **          is p
343e0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
343f0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
34400 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6d 70  eter to the comp
34410 61 72 69 73 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  arison.**       
34420 20 20 20 66 75 6e 63 74 69 6f 6e 20 46 20 66 6f     function F fo
34430 72 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  r all subsequent
34440 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
34450 46 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 31  F..**.** {H16621
34460 7d 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  } A call to [sql
34470 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
34480 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50 2c 46 29  ation(B,X,E,P,F)
34490 5d 20 69 73 20 65 78 61 63 74 6c 79 0a 2a 2a 20  ] is exactly.** 
344a0 20 20 20 20 20 20 20 20 20 74 68 65 20 73 61 6d           the sam
344b0 65 20 61 73 20 61 20 63 61 6c 6c 20 74 6f 20 5b  e as a call to [
344c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
344d0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 20 77  ollation_v2()] w
344e0 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ith.**          
344f0 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74  the same paramet
34500 65 72 73 20 61 6e 64 20 61 20 4e 55 4c 4c 20 64  ers and a NULL d
34510 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2a 0a 2a 2a  estructor..**.**
34520 20 7b 48 31 36 36 32 34 7d 20 46 6f 6c 6c 6f 77   {H16624} Follow
34530 69 6e 67 20 61 20 5b 73 71 6c 69 74 65 33 5f 63  ing a [sqlite3_c
34540 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
34550 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
34560 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  ,.**          SQ
34570 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 63 6f  Lite uses the co
34580 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69 6f  mparison functio
34590 6e 20 46 20 66 6f 72 20 61 6c 6c 20 74 65 78 74  n F for all text
345a0 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20   comparison.**  
345b0 20 20 20 20 20 20 20 20 6f 70 65 72 61 74 69 6f          operatio
345c0 6e 73 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ns on the [datab
345d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
345e0 42 20 6f 6e 20 74 65 78 74 20 76 61 6c 75 65 73  B on text values
345f0 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20 20   that.**        
34600 20 20 75 73 65 20 74 68 65 20 63 6f 6c 6c 61 74    use the collat
34610 69 6e 67 20 73 65 71 75 65 6e 63 65 20 6e 61 6d  ing sequence nam
34620 65 64 20 58 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ed X..**.** {H16
34630 36 32 37 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  627} The [sqlite
34640 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
34650 6f 6e 31 36 28 42 2c 58 2c 45 2c 50 2c 46 29 5d  on16(B,X,E,P,F)]
34660 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 0a   works the same.
34670 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20 5b  **          as [
34680 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
34690 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45 2c 50  ollation(B,X,E,P
346a0 2c 46 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  ,F)] except that
346b0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
346c0 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20   collation name 
346d0 58 20 69 73 20 75 6e 64 65 72 73 74 6f 6f 64 20  X is understood 
346e0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
346f0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a 2a  ive byte order.*
34700 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 74 65  *          inste
34710 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a 0a  ad of UTF-8..**.
34720 2a 2a 20 7b 48 31 36 36 33 30 7d 20 57 68 65 6e  ** {H16630} When
34730 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6d 70 61 72   multiple compar
34740 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 61  ison functions a
34750 72 65 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72  re available for
34760 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20   the same.**    
34770 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6e 67 20        collating 
34780 73 65 71 75 65 6e 63 65 2c 20 53 51 4c 69 74 65  sequence, SQLite
34790 20 63 68 6f 6f 73 65 73 20 74 68 65 20 6f 6e 65   chooses the one
347a0 20 77 68 6f 73 65 20 74 65 78 74 20 65 6e 63 6f   whose text enco
347b0 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ding.**         
347c0 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65   requires the le
347d0 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f  ast amount of co
347e0 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 74 68  nversion from th
347f0 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 20 20 20  e default.**    
34800 20 20 20 20 20 20 74 65 78 74 20 65 6e 63 6f 64        text encod
34810 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62  ing of the datab
34820 61 73 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ase..*/.int sqli
34830 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
34840 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  tion(.  sqlite3*
34850 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
34860 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
34870 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
34880 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  *,.  int(*xCompa
34890 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
348a0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
348b0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
348c0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
348d0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
348e0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
348f0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
34900 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
34910 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e  , .  void*,.  in
34920 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
34930 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
34940 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
34950 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
34960 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
34970 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
34980 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
34990 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
349a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d  const void *zNam
349b0 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  e,.  int eTextRe
349c0 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
349d0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
349e0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
349f0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
34a00 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
34a10 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69  API3REF: Collati
34a20 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61  on Needed Callba
34a30 63 6b 73 20 7b 48 31 36 37 30 30 7d 20 3c 53 32  cks {H16700} <S2
34a40 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61  0300>.**.** To a
34a50 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
34a60 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
34a70 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
34a80 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
34a90 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
34aa0 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
34ab0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
34ac0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
34ad0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
34ae0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
34af0 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 20 77 68   to be called wh
34b00 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
34b10 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  ned collation.**
34b20 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71   sequence is req
34b30 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  uired..**.** If 
34b40 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
34b50 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
34b60 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
34b70 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
34b80 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  API,.** then it 
34b90 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61  is passed the na
34ba0 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64  mes of undefined
34bb0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
34bc0 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a  nces as strings.
34bd0 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  ** encoded in UT
34be0 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d 20 49 66  F-8. {H16703} If
34bf0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
34c00 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
34c10 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61   used,.** the na
34c20 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61  mes are passed a
34c30 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
34c40 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
34c50 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c  order..** A call
34c60 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74   to either funct
34c70 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79  ion replaces any
34c80 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61   existing callba
34c90 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ck..**.** When t
34ca0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
34cb0 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
34cc0 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
34cd0 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
34ce0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
34cf0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
34d00 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
34d10 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
34d20 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
34d30 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
34d40 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
34d50 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
34d60 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
34d70 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
34d80 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
34d90 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
34da0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
34db0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
34dc0 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
34dd0 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
34de0 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
34df0 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
34e00 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
34e10 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
34e20 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
34e30 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
34e40 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
34e50 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a  tion sequence..*
34e60 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
34e70 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
34e80 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
34e90 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
34ea0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
34eb0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34ec0 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
34ed0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
34ee0 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
34ef0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34f00 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
34f10 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
34f20 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 32 7d 20  .**.** {H16702} 
34f30 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
34f40 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
34f50 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 44  llation_needed(D
34f60 2c 50 2c 46 29 5d 0a 2a 2a 20 20 20 20 20 20 20  ,P,F)].**       
34f70 20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63     or [sqlite3_c
34f80 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
34f90 36 28 44 2c 50 2c 46 29 5d 20 63 61 75 73 65 73  6(D,P,F)] causes
34fa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
34fb0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
34fc0 63 74 69 6f 6e 5d 20 44 20 74 6f 20 69 6e 76 6f  ction] D to invo
34fd0 6b 65 20 63 61 6c 6c 62 61 63 6b 20 46 20 77 69  ke callback F wi
34fe0 74 68 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20  th first.**     
34ff0 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 50       parameter P
35000 20 77 68 65 6e 65 76 65 72 20 69 74 20 6e 65 65   whenever it nee
35010 64 73 20 61 20 63 6f 6d 70 61 72 69 73 6f 6e 20  ds a comparison 
35020 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 61 0a 2a  function for a.*
35030 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
35040 74 69 6e 67 20 73 65 71 75 65 6e 63 65 20 74 68  ting sequence th
35050 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b  at it does not k
35060 6e 6f 77 20 61 62 6f 75 74 2e 0a 2a 2a 0a 2a 2a  now about..**.**
35070 20 7b 48 31 36 37 30 34 7d 20 45 61 63 68 20 73   {H16704} Each s
35080 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
35090 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  o [sqlite3_colla
350a0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 6f  tion_needed()] o
350b0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
350c0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
350d0 5f 6e 65 65 64 65 64 31 36 28 29 5d 20 6f 76 65  _needed16()] ove
350e0 72 72 69 64 65 73 20 74 68 65 20 63 61 6c 6c 62  rrides the callb
350f0 61 63 6b 20 72 65 67 69 73 74 65 72 65 64 0a 2a  ack registered.*
35100 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74 68  *          on th
35110 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
35120 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 62 79 20   connection] by 
35130 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 65  prior calls to e
35140 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  ither.**        
35150 20 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a    interface..**.
35160 2a 2a 20 7b 48 31 36 37 30 36 7d 20 54 68 65 20  ** {H16706} The 
35170 6e 61 6d 65 20 6f 66 20 74 68 65 20 72 65 71 75  name of the requ
35180 65 73 74 65 64 20 63 6f 6c 6c 61 74 69 6e 67 20  ested collating 
35190 66 75 6e 63 74 69 6f 6e 20 70 61 73 73 65 64 20  function passed 
351a0 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  in the.**       
351b0 20 20 20 34 74 68 20 70 61 72 61 6d 65 74 65 72     4th parameter
351c0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
351d0 20 69 73 20 69 6e 20 55 54 46 2d 38 20 69 66 20   is in UTF-8 if 
351e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
351f0 20 20 20 20 20 20 20 20 20 77 61 73 20 72 65 67           was reg
35200 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b 73  istered using [s
35210 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
35220 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 0a 2a  _needed()] and.*
35230 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 69 6e  *          is in
35240 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
35250 79 74 65 20 6f 72 64 65 72 20 69 66 20 74 68 65  yte order if the
35260 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 0a 2a 2a   callback was.**
35270 20 20 20 20 20 20 20 20 20 20 72 65 67 69 73 74            regist
35280 65 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ered using [sqli
35290 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
352a0 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e  eded16()]..*/.in
352b0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
352c0 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71  ion_needed(.  sq
352d0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
352e0 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
352f0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
35300 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63  eTextRep,const c
35310 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  har*).);.int sql
35320 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
35330 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74  eeded16(.  sqlit
35340 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  e3*, .  void*,. 
35350 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
35360 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
35370 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  tRep,const void*
35380 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63  ).);../*.** Spec
35390 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20  ify the key for 
353a0 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74  an encrypted dat
353b0 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75  abase.  This rou
353c0 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  tine should be.*
353d0 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61  * called right a
353e0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  fter sqlite3_ope
353f0 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n()..**.** The c
35400 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
35410 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
35420 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
35430 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
35440 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
35450 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  /.int sqlite3_ke
35460 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
35470 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
35480 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
35490 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
354a0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
354b0 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
354c0 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a    /* The key */.
354d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65  );../*.** Change
354e0 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f   the key on an o
354f0 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49  pen database.  I
35500 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  f the current da
35510 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a  tabase is not.**
35520 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73   encrypted, this
35530 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e   routine will en
35540 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e  crypt it.  If pN
35550 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30  ew==0 or nNew==0
35560 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  , the.** databas
35570 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a  e is decrypted..
35580 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
35590 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
355a0 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
355b0 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
355c0 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
355d0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
355e0 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a   sqlite3_rekey(.
355f0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
35600 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35610 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
35620 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
35630 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
35640 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
35650 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f  * The new key */
35660 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
35670 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65  REF: Suspend Exe
35680 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f  cution For A Sho
35690 72 74 20 54 69 6d 65 20 7b 48 31 30 35 33 30 7d  rt Time {H10530}
356a0 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S40410>.**.** 
356b0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
356c0 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  p() function cau
356d0 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
356e0 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
356f0 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
35700 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
35710 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
35720 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
35730 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
35740 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  .**.** If the op
35750 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64  erating system d
35760 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20  oes not support 
35770 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77  sleep requests w
35780 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f  ith.** milliseco
35790 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69  nd time resoluti
357a0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d  on, then the tim
357b0 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65  e will be rounde
357c0 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e  d up to.** the n
357d0 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54  earest second. T
357e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
357f0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
35800 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72  ep actually.** r
35810 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
35820 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
35830 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
35840 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70  **.** SQLite imp
35850 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
35860 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
35870 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
35880 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
35890 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
358a0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
358b0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
358c0 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 33 7d 20 54  **.** {H10533} T
358d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65  he [sqlite3_slee
358e0 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20  p(M)] interface 
358f0 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 6c 65  invokes the xSle
35900 65 70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  ep.**          m
35910 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
35920 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
35930 73 7c 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20  s|VFS] in order 
35940 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  to.**          s
35950 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
35960 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   of the current 
35970 74 68 72 65 61 64 20 66 6f 72 20 61 74 20 6c 65  thread for at le
35980 61 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ast.**          
35990 4d 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a  M milliseconds..
359a0 2a 2a 0a 2a 2a 20 7b 48 31 30 35 33 36 7d 20 54  **.** {H10536} T
359b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6c 65 65  he [sqlite3_slee
359c0 70 28 4d 29 5d 20 69 6e 74 65 72 66 61 63 65 20  p(M)] interface 
359d0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
359e0 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  er of.**        
359f0 20 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f    milliseconds o
35a00 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
35a10 20 72 65 71 75 65 73 74 65 64 20 6f 66 20 74 68   requested of th
35a20 65 20 6f 70 65 72 61 74 69 6e 67 0a 2a 2a 20 20  e operating.**  
35a30 20 20 20 20 20 20 20 20 73 79 73 74 65 6d 2c 20          system, 
35a40 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20 6c  which might be l
35a50 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 70  arger than the p
35a60 61 72 61 6d 65 74 65 72 20 4d 2e 0a 2a 2f 0a 69  arameter M..*/.i
35a70 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  nt sqlite3_sleep
35a80 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
35a90 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
35aa0 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69  The Folder Holdi
35ab0 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c  ng Temporary Fil
35ac0 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53 32 30  es {H10310} <S20
35ad0 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  000>.**.** If th
35ae0 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  is global variab
35af0 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  le is made to po
35b00 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
35b10 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20  which is.** the 
35b20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72  name of a folder
35b30 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f   (a.k.a. directo
35b40 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65  ry), then all te
35b50 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a  mporary files.**
35b60 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69   created by SQLi
35b70 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65  te will be place
35b80 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74  d in that direct
35b90 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76 61  ory.  If this va
35ba0 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e  riable.** is a N
35bb0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
35bc0 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d  n SQLite perform
35bd0 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61  s a search for a
35be0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a  n appropriate.**
35bf0 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20   temporary file 
35c00 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
35c10 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
35c20 74 6f 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  to modify this v
35c30 61 72 69 61 62 6c 65 20 6f 6e 63 65 20 61 20 5b  ariable once a [
35c40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35c50 69 6f 6e 5d 0a 2a 2a 20 68 61 73 20 62 65 65 6e  ion].** has been
35c60 20 6f 70 65 6e 65 64 2e 20 20 49 74 20 69 73 20   opened.  It is 
35c70 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68  intended that th
35c80 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73  is variable be s
35c90 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61  et once.** as pa
35ca0 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e  rt of process in
35cb0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
35cc0 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69   before any SQLi
35cd0 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  te interface.** 
35ce0 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65  routines have be
35cf0 65 6e 20 63 61 6c 6c 20 61 6e 64 20 72 65 6d 61  en call and rema
35d00 69 6e 20 75 6e 63 68 61 6e 67 65 64 20 74 68 65  in unchanged the
35d10 72 65 61 66 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49  reafter..*/.SQLI
35d20 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a  TE_EXTERN char *
35d30 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
35d40 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ectory;../*.** C
35d50 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f  API3REF: Test Fo
35d60 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f  r Auto-Commit Mo
35d70 64 65 20 7b 48 31 32 39 33 30 7d 20 3c 53 36 30  de {H12930} <S60
35d80 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  200>.** KEYWORDS
35d90 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  : {autocommit mo
35da0 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  de}.**.** The sq
35db0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
35dc0 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  mmit() interface
35dd0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
35de0 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  o or.** zero if 
35df0 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61  the given databa
35e00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
35e10 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75   or is not in au
35e20 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a  tocommit mode,.*
35e30 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
35e40 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   Autocommit mode
35e50 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c   is on by defaul
35e60 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74  t..** Autocommit
35e70 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65   mode is disable
35e80 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73  d by a [BEGIN] s
35e90 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41 75 74  tatement..** Aut
35ea0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
35eb0 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20  re-enabled by a 
35ec0 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c  [COMMIT] or [ROL
35ed0 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  LBACK]..**.** If
35ee0 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f   certain kinds o
35ef0 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f  f errors occur o
35f00 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69  n a statement wi
35f10 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61  thin a multi-sta
35f20 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61  tement.** transa
35f30 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e  ction (errors in
35f40 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f  cluding [SQLITE_
35f50 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  FULL], [SQLITE_I
35f60 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  OERR],.** [SQLIT
35f70 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54  E_NOMEM], [SQLIT
35f80 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51  E_BUSY], and [SQ
35f90 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29  LITE_INTERRUPT])
35fa0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61   then the.** tra
35fb0 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62  nsaction might b
35fc0 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
35fd0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
35fe0 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a  e only way to.**
35ff0 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65   find out whethe
36000 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  r SQLite automat
36010 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
36020 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
36030 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65  on after.** an e
36040 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74  rror is to use t
36050 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
36060 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
36070 2a 2a 0a 2a 2a 20 7b 48 31 32 39 33 31 7d 20 54  **.** {H12931} T
36080 68 65 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  he [sqlite3_get_
36090 61 75 74 6f 63 6f 6d 6d 69 74 28 44 29 5d 20 69  autocommit(D)] i
360a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
360b0 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20   non-zero or.** 
360c0 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20 69 66           zero if
360d0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
360e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 69 73 20  onnection] D is 
360f0 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
36100 6f 63 6f 6d 6d 69 74 0a 2a 2a 20 20 20 20 20 20  ocommit.**      
36110 20 20 20 20 6d 6f 64 65 2c 20 72 65 73 70 65 63      mode, respec
36120 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tively..**.** {H
36130 31 32 39 33 32 7d 20 41 75 74 6f 63 6f 6d 6d 69  12932} Autocommi
36140 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20  t mode is on by 
36150 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b  default..**.** {
36160 48 31 32 39 33 33 7d 20 41 75 74 6f 63 6f 6d 6d  H12933} Autocomm
36170 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62  it mode is disab
36180 6c 65 64 20 62 79 20 61 20 73 75 63 63 65 73 73  led by a success
36190 66 75 6c 20 5b 42 45 47 49 4e 5d 20 73 74 61 74  ful [BEGIN] stat
361a0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ement..**.** {H1
361b0 32 39 33 34 7d 20 41 75 74 6f 63 6f 6d 6d 69 74  2934} Autocommit
361c0 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
361d0 20 62 79 20 61 20 73 75 63 63 65 73 73 66 75 6c   by a successful
361e0 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
361f0 4c 4c 42 41 43 4b 5d 0a 2a 2a 20 20 20 20 20 20  LLBACK].**      
36200 20 20 20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a      statement..*
36210 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
36220 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 39 33 36 7d  :.**.** {A12936}
36230 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
36240 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61  ad changes the a
36250 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73  utocommit status
36260 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
36270 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e  .**          con
36280 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
36290 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75  is routine is ru
362a0 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nning, then the 
362b0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
362c0 20 20 20 20 20 20 20 20 20 69 73 20 75 6e 64 65           is unde
362d0 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
362e0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
362f0 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  mmit(sqlite3*);.
36300 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36310 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61   Find The Databa
36320 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50  se Handle Of A P
36330 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
36340 74 20 7b 48 31 33 31 32 30 7d 20 3c 53 36 30 36  t {H13120} <S606
36350 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
36360 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
36370 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
36380 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
36390 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
363a0 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61  le.** to which a
363b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
363c0 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20  ment] belongs.  
363d0 54 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e  The database han
363e0 64 6c 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a  dle returned by.
363f0 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  ** sqlite3_db_ha
36400 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65  ndle is the same
36410 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
36420 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69   that was the fi
36430 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
36440 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
36450 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61  prepare_v2()] ca
36460 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61  ll (or its varia
36470 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73  nts) that was us
36480 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20  ed to.** create 
36490 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  the statement in
364a0 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65   the first place
364b0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
364c0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 32  TS:.**.** {H1312
364d0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
364e0 64 62 5f 68 61 6e 64 6c 65 28 53 29 5d 20 69 6e  db_handle(S)] in
364f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
36500 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20  a pointer.**    
36510 20 20 20 20 20 20 74 6f 20 74 68 65 20 5b 64 61        to the [da
36520 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36530 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  n] associated wi
36540 74 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  th the.**       
36550 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
36560 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 73 71  tement] S..*/.sq
36570 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
36580 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
36590 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
365a0 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74  CAPI3REF: Find t
365b0 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64  he next prepared
365c0 20 73 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 31   statement {H131
365d0 34 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a 0a  40} <S60600>.**.
365e0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
365f0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
36600 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ter to the next 
36610 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
36620 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53  ent] after.** pS
36630 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  tmt associated w
36640 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
36650 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44  e connection] pD
36660 62 2e 20 20 49 66 20 70 53 74 6d 74 20 69 73 20  b.  If pStmt is 
36670 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69  NULL.** then thi
36680 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
36690 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
366a0 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61   the first prepa
366b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
366c0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
366d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
366e0 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 49  nnection pDb.  I
366f0 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74  f no prepared st
36700 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73  atement.** satis
36710 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69  fies the conditi
36720 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ons of this rout
36730 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ine, it returns 
36740 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  NULL..**.** INVA
36750 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
36760 31 33 31 34 33 7d 20 49 66 20 44 20 69 73 20 61  13143} If D is a
36770 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36780 63 74 69 6f 6e 5d 20 74 68 61 74 20 68 6f 6c 64  ction] that hold
36790 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
367a0 20 20 20 20 20 20 20 20 20 20 75 6e 66 69 6e 61            unfina
367b0 6c 69 7a 65 64 20 5b 70 72 65 70 61 72 65 64 20  lized [prepared 
367c0 73 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20  statements] and 
367d0 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  S is a NULL poin
367e0 74 65 72 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ter,.**         
367f0 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6e   then [sqlite3_n
36800 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20  ext_stmt(D, S)] 
36810 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65  routine shall re
36820 74 75 72 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  turn a pointer.*
36830 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20 6f 6e  *          to on
36840 65 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65  e of the prepare
36850 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73  d statements ass
36860 6f 63 69 61 74 65 64 20 77 69 74 68 20 44 2e 0a  ociated with D..
36870 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34 36 7d 20 49  **.** {H13146} I
36880 66 20 44 20 69 73 20 61 20 5b 64 61 74 61 62 61  f D is a [databa
36890 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
368a0 68 61 74 20 68 6f 6c 64 73 20 6e 6f 20 75 6e 66  hat holds no unf
368b0 69 6e 61 6c 69 7a 65 64 0a 2a 2a 20 20 20 20 20  inalized.**     
368c0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
368d0 74 61 74 65 6d 65 6e 74 73 5d 20 61 6e 64 20 53  tatements] and S
368e0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
368f0 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  er, then.**     
36900 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65       [sqlite3_ne
36910 78 74 5f 73 74 6d 74 28 44 2c 20 53 29 5d 20 72  xt_stmt(D, S)] r
36920 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74  outine shall ret
36930 75 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  urn a NULL point
36940 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 34  er..**.** {H1314
36950 39 7d 20 49 66 20 53 20 69 73 20 61 20 5b 70 72  9} If S is a [pr
36960 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
36970 5d 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61  ] in the [databa
36980 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
36990 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64  .**          and
369a0 20 53 20 69 73 20 6e 6f 74 20 74 68 65 20 6c 61   S is not the la
369b0 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
369c0 65 6d 65 6e 74 20 69 6e 20 44 2c 20 74 68 65 6e  ement in D, then
369d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
369e0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
369f0 44 2c 20 53 29 5d 20 72 6f 75 74 69 6e 65 20 73  D, S)] routine s
36a00 68 61 6c 6c 20 72 65 74 75 72 6e 20 61 20 70 6f  hall return a po
36a10 69 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  inter.**        
36a20 20 20 74 6f 20 74 68 65 20 6e 65 78 74 20 70 72    to the next pr
36a30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
36a40 20 69 6e 20 44 20 61 66 74 65 72 20 53 2e 0a 2a   in D after S..*
36a50 2a 0a 2a 2a 20 7b 48 31 33 31 35 32 7d 20 49 66  *.** {H13152} If
36a60 20 53 20 69 73 20 74 68 65 20 6c 61 73 74 20 5b   S is the last [
36a70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
36a80 6e 74 5d 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20  nt] in the.**   
36a90 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
36aa0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74   connection] D t
36ab0 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
36ac0 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 20 53 29  _next_stmt(D, S)
36ad0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f  ].**          ro
36ae0 75 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75  utine shall retu
36af0 72 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  rn a NULL pointe
36b00 72 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54  r..**.** ASSUMPT
36b10 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 33  IONS:.**.** {A13
36b20 31 35 34 7d 20 54 68 65 20 5b 64 61 74 61 62 61  154} The [databa
36b30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
36b40 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61  ointer D in a ca
36b50 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ll to.**        
36b60 20 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f    [sqlite3_next_
36b70 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20  stmt(D,S)] must 
36b80 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e  refer to an open
36b90 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20   database.**    
36ba0 20 20 20 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e        connection
36bb0 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c   and in particul
36bc0 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61  ar must not be a
36bd0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
36be0 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  /.sqlite3_stmt *
36bf0 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
36c00 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20  t(sqlite3 *pDb, 
36c10 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
36c20 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
36c30 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e  I3REF: Commit An
36c40 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66  d Rollback Notif
36c50 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
36c60 73 20 7b 48 31 32 39 35 30 7d 20 3c 53 36 30 34  s {H12950} <S604
36c70 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
36c80 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
36c90 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
36ca0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
36cb0 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
36cc0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
36cd0 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
36ce0 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64  ion is committed
36cf0 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63  ..** Any callbac
36d00 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
36d10 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ous call to sqli
36d20 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
36d30 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
36d40 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
36d50 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
36d60 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  den..** The sqli
36d70 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
36d80 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
36d90 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
36da0 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
36db0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
36dc0 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
36dd0 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64  ion is committed
36de0 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63  ..** Any callbac
36df0 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
36e00 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ous call to sqli
36e10 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
36e20 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ).** for the sam
36e30 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
36e40 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64  ction is overrid
36e50 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41 72 67  den..** The pArg
36e60 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73   argument is pas
36e70 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74  sed through to t
36e80 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  he callback..** 
36e90 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
36ea0 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b  on a commit hook
36eb0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
36ec0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74  s non-zero,.** t
36ed0 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69  hen the commit i
36ee0 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
36ef0 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a   a rollback..**.
36f00 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 66 75  ** If another fu
36f10 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65 76 69  nction was previ
36f20 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65 64  ously registered
36f30 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67 20 76 61  , its.** pArg va
36f40 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
36f50 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55 4c 4c    Otherwise NULL
36f60 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
36f70 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 6e 67 20  .** Registering 
36f80 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20  a NULL function 
36f90 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c  disables the cal
36fa0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72  lback..**.** For
36fb0 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
36fc0 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61   this API, a tra
36fd0 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64  nsaction is said
36fe0 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a   to have been.**
36ff0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20   rolled back if 
37000 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c  an explicit "ROL
37010 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74  LBACK" statement
37020 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72   is executed, or
37030 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20  .** an error or 
37040 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65  constraint cause
37050 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f  s an implicit ro
37060 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e  llback to occur.
37070 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b  .** The rollback
37080 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74   callback is not
37090 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72   invoked if a tr
370a0 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20  ansaction is.** 
370b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
370c0 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73  lled back becaus
370d0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
370e0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
370f0 73 65 64 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c  sed..** The roll
37100 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  back callback is
37110 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20   not invoked if 
37120 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
37130 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
37140 62 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74  because a commit
37150 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
37160 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 20  ed non-zero..** 
37170 3c 74 6f 64 6f 3e 20 43 68 65 63 6b 20 6f 6e 20  <todo> Check on 
37180 74 68 69 73 20 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a  this </todo>.**.
37190 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
371a0 2a 0a 2a 2a 20 7b 48 31 32 39 35 31 7d 20 54 68  *.** {H12951} Th
371b0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  e [sqlite3_commi
371c0 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  t_hook(D,F,P)] i
371d0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
371e0 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  rs the.**       
371f0 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63     callback func
37200 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69 6e 76  tion F to be inv
37210 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65  oked with argume
37220 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a  nt P whenever.**
37230 20 20 20 20 20 20 20 20 20 20 61 20 74 72 61 6e            a tran
37240 73 61 63 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 20  saction commits 
37250 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
37260 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a   connection] D..
37270 2a 2a 0a 2a 2a 20 7b 48 31 32 39 35 32 7d 20 54  **.** {H12952} T
37280 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  he [sqlite3_comm
37290 69 74 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  it_hook(D,F,P)] 
372a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
372b0 73 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74  s the P argument
372c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f  .**          fro
372d0 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  m the previous c
372e0 61 6c 6c 20 77 69 74 68 20 74 68 65 20 73 61 6d  all with the sam
372f0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37300 65 63 74 69 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20  ection] D,.**   
37310 20 20 20 20 20 20 20 6f 72 20 4e 55 4c 4c 20 6f         or NULL o
37320 6e 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  n the first call
37330 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
37340 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
37350 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b  ction D..**.** {
37360 48 31 32 39 35 33 7d 20 45 61 63 68 20 63 61 6c  H12953} Each cal
37370 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
37380 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 6f 76 65  mmit_hook()] ove
37390 72 77 72 69 74 65 73 20 74 68 65 20 63 61 6c 6c  rwrites the call
373a0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20  back.**         
373b0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 70   registered by p
373c0 72 69 6f 72 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a  rior calls..**.*
373d0 2a 20 7b 48 31 32 39 35 34 7d 20 49 66 20 74 68  * {H12954} If th
373e0 65 20 46 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  e F argument to 
373f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  [sqlite3_commit_
37400 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69 73 20  hook(D,F,P)] is 
37410 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  NULL.**         
37420 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
37430 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 69   hook callback i
37440 73 20 63 61 6e 63 65 6c 65 64 20 61 6e 64 20 6e  s canceled and n
37450 6f 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20  o callback.**   
37460 20 20 20 20 20 20 20 69 73 20 69 6e 76 6f 6b 65         is invoke
37470 64 20 77 68 65 6e 20 61 20 74 72 61 6e 73 61 63  d when a transac
37480 74 69 6f 6e 20 63 6f 6d 6d 69 74 73 2e 0a 2a 2a  tion commits..**
37490 0a 2a 2a 20 7b 48 31 32 39 35 35 7d 20 49 66 20  .** {H12955} If 
374a0 74 68 65 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62  the commit callb
374b0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
374c0 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20 63 6f  zero then the co
374d0 6d 6d 69 74 20 69 73 0a 2a 2a 20 20 20 20 20 20  mmit is.**      
374e0 20 20 20 20 63 6f 6e 76 65 72 74 65 64 20 69 6e      converted in
374f0 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  to a rollback..*
37500 2a 0a 2a 2a 20 7b 48 31 32 39 36 31 7d 20 54 68  *.** {H12961} Th
37510 65 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  e [sqlite3_rollb
37520 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d  ack_hook(D,F,P)]
37530 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
37540 74 65 72 73 20 74 68 65 0a 2a 2a 20 20 20 20 20  ters the.**     
37550 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 66 75       callback fu
37560 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65 20 69  nction F to be i
37570 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75  nvoked with argu
37580 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a  ment P whenever.
37590 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 74 72  **          a tr
375a0 61 6e 73 61 63 74 69 6f 6e 20 72 6f 6c 6c 73 20  ansaction rolls 
375b0 62 61 63 6b 20 6f 6e 20 74 68 65 20 5b 64 61 74  back on the [dat
375c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
375d0 5d 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39  ] D..**.** {H129
375e0 36 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  62} The [sqlite3
375f0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44  _rollback_hook(D
37600 2c 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65  ,F,P)] interface
37610 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 0a 2a   returns the P.*
37620 2a 20 20 20 20 20 20 20 20 20 20 61 72 67 75 6d  *          argum
37630 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
37640 76 69 6f 75 73 20 63 61 6c 6c 20 77 69 74 68 20  vious call with 
37650 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20  the same.**     
37660 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
37670 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72  onnection] D, or
37680 20 4e 55 4c 4c 20 6f 6e 20 74 68 65 20 66 69 72   NULL on the fir
37690 73 74 20 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  st call.**      
376a0 20 20 20 20 66 6f 72 20 61 20 70 61 72 74 69 63      for a partic
376b0 75 6c 61 72 20 64 61 74 61 62 61 73 65 20 63 6f  ular database co
376c0 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a  nnection D..**.*
376d0 2a 20 7b 48 31 32 39 36 33 7d 20 45 61 63 68 20  * {H12963} Each 
376e0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
376f0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
37700 5d 20 6f 76 65 72 77 72 69 74 65 73 20 74 68 65  ] overwrites the
37710 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 20 20 20   callback.**    
37720 20 20 20 20 20 20 72 65 67 69 73 74 65 72 65 64        registered
37730 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 2e   by prior calls.
37740 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 36 34 7d 20  .**.** {H12964} 
37750 49 66 20 74 68 65 20 46 20 61 72 67 75 6d 65 6e  If the F argumen
37760 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 6f  t to [sqlite3_ro
37770 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 46 2c  llback_hook(D,F,
37780 50 29 5d 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 20  P)] is NULL.**  
37790 20 20 20 20 20 20 20 20 74 68 65 6e 20 74 68 65          then the
377a0 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63   rollback hook c
377b0 61 6c 6c 62 61 63 6b 20 69 73 20 63 61 6e 63 65  allback is cance
377c0 6c 65 64 20 61 6e 64 20 6e 6f 20 63 61 6c 6c 62  led and no callb
377d0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
377e0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
377f0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 72 6f  a transaction ro
37800 6c 6c 73 20 62 61 63 6b 2e 0a 2a 2f 0a 76 6f 69  lls back..*/.voi
37810 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  d *sqlite3_commi
37820 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  t_hook(sqlite3*,
37830 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
37840 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71  void*);.void *sq
37850 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
37860 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ook(sqlite3*, vo
37870 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76  id(*)(void *), v
37880 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
37890 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61  PI3REF: Data Cha
378a0 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  nge Notification
378b0 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39   Callbacks {H129
378c0 37 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a  70} <S60400>.**.
378d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
378e0 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74  pdate_hook() int
378f0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
37900 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
37910 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
37920 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37930 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65  ction] identifie
37940 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
37950 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65  rgument.** to be
37960 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
37970 72 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74  r a row is updat
37980 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20  ed, inserted or 
37990 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20  deleted..** Any 
379a0 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
379b0 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
379c0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
379d0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
379e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
379f0 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
37a00 65 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  en..**.** The se
37a10 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
37a20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
37a30 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e  e function to in
37a40 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72  voke when a.** r
37a50 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69  ow is updated, i
37a60 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74  nserted or delet
37a70 65 64 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ed..** The first
37a80 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
37a90 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
37aa0 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
37ab0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
37ac0 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
37ad0 6f 6f 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65  ook()..** The se
37ae0 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72  cond callback ar
37af0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
37b00 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d   [SQLITE_INSERT]
37b10 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  , [SQLITE_DELETE
37b20 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
37b30 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64  _UPDATE], depend
37b40 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61  ing on the opera
37b50 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64  tion that caused
37b60 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
37b70 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a   to be invoked..
37b80 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 6e 64  ** The third and
37b90 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
37ba0 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  s to the callbac
37bb0 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65  k contain pointe
37bc0 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  rs to the.** dat
37bd0 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20  abase and table 
37be0 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  name containing 
37bf0 74 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77  the affected row
37c00 2e 0a 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63  ..** The final c
37c10 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
37c20 72 20 69 73 20 74 68 65 20 72 6f 77 69 64 20 6f  r is the rowid o
37c30 66 20 74 68 65 20 72 6f 77 2e 20 49 6e 20 74 68  f the row. In th
37c40 65 20 63 61 73 65 20 6f 66 0a 2a 2a 20 61 6e 20  e case of.** an 
37c50 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20  update, this is 
37c60 74 68 65 20 72 6f 77 69 64 20 61 66 74 65 72 20  the rowid after 
37c70 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73  the update takes
37c80 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   place..**.** Th
37c90 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73  e update hook is
37ca0 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65   not invoked whe
37cb0 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65  n internal syste
37cc0 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20  m tables are.** 
37cd0 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73  modified (i.e. s
37ce0 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64  qlite_master and
37cf0 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65   sqlite_sequence
37d00 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  )..**.** If anot
37d10 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77 61 73  her function was
37d20 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69   previously regi
37d30 73 74 65 72 65 64 2c 20 69 74 73 20 70 41 72 67  stered, its pArg
37d40 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74   value.** is ret
37d50 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
37d60 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  e NULL is return
37d70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
37d80 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
37d90 39 37 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  971} The [sqlite
37da0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
37db0 46 2c 50 29 5d 20 69 6e 74 65 72 66 61 63 65 20  F,P)] interface 
37dc0 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
37dd0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ack.**          
37de0 66 75 6e 63 74 69 6f 6e 20 46 20 74 6f 20 62 65  function F to be
37df0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 69   invoked with fi
37e00 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 50 20  rst parameter P 
37e10 77 68 65 6e 65 76 65 72 0a 2a 2a 20 20 20 20 20  whenever.**     
37e20 20 20 20 20 20 61 20 74 61 62 6c 65 20 72 6f 77       a table row
37e30 20 69 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e   is modified, in
37e40 73 65 72 74 65 64 2c 20 6f 72 20 64 65 6c 65 74  serted, or delet
37e50 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ed on.**        
37e60 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20    the [database 
37e70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a  connection] D..*
37e80 2a 0a 2a 2a 20 7b 48 31 32 39 37 33 7d 20 54 68  *.** {H12973} Th
37e90 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
37ea0 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20 69  e_hook(D,F,P)] i
37eb0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
37ec0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20   the value.**   
37ed0 20 20 20 20 20 20 20 6f 66 20 50 20 66 6f 72 20         of P for 
37ee0 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
37ef0 6c 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  l on the same [d
37f00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37f10 6f 6e 5d 20 44 2c 0a 2a 2a 20 20 20 20 20 20 20  on] D,.**       
37f20 20 20 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 20 74     or NULL for t
37f30 68 65 20 66 69 72 73 74 20 63 61 6c 6c 2e 0a 2a  he first call..*
37f40 2a 0a 2a 2a 20 7b 48 31 32 39 37 35 7d 20 49 66  *.** {H12975} If
37f50 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
37f60 20 63 61 6c 6c 62 61 63 6b 20 46 20 69 6e 20 5b   callback F in [
37f70 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
37f80 6f 6f 6b 28 44 2c 46 2c 50 29 5d 0a 2a 2a 20 20  ook(D,F,P)].**  
37f90 20 20 20 20 20 20 20 20 69 73 20 4e 55 4c 4c 20          is NULL 
37fa0 74 68 65 6e 20 74 68 65 20 6e 6f 20 75 70 64 61  then the no upda
37fb0 74 65 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65  te callbacks are
37fc0 20 6d 61 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   made..**.** {H1
37fd0 32 39 37 37 7d 20 45 61 63 68 20 63 61 6c 6c 20  2977} Each call 
37fe0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61  to [sqlite3_upda
37ff0 74 65 5f 68 6f 6f 6b 28 44 2c 46 2c 50 29 5d 20  te_hook(D,F,P)] 
38000 6f 76 65 72 72 69 64 65 73 20 70 72 69 6f 72 20  overrides prior 
38010 63 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20  calls.**        
38020 20 20 74 6f 20 74 68 65 20 73 61 6d 65 20 69 6e    to the same in
38030 74 65 72 66 61 63 65 20 6f 6e 20 74 68 65 20 73  terface on the s
38040 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
38050 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
38060 2a 2a 20 7b 48 31 32 39 37 39 7d 20 54 68 65 20  ** {H12979} The 
38070 75 70 64 61 74 65 20 68 6f 6f 6b 20 63 61 6c 6c  update hook call
38080 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  back is not invo
38090 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
380a0 6c 20 73 79 73 74 65 6d 0a 2a 2a 20 20 20 20 20  l system.**     
380b0 20 20 20 20 20 74 61 62 6c 65 73 20 73 75 63 68       tables such
380c0 20 61 73 20 73 71 6c 69 74 65 5f 6d 61 73 74 65   as sqlite_maste
380d0 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
380e0 75 65 6e 63 65 20 61 72 65 20 6d 6f 64 69 66 69  uence are modifi
380f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 38  ed..**.** {H1298
38100 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  1} The second pa
38110 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 75  rameter to the u
38120 70 64 61 74 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  pdate callback.*
38130 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 6f 6e  *          is on
38140 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53  e of [SQLITE_INS
38150 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45  ERT], [SQLITE_DE
38160 4c 45 54 45 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LETE] or [SQLITE
38170 5f 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 20 20 20  _UPDATE],.**    
38180 20 20 20 20 20 20 64 65 70 65 6e 64 69 6e 67 20        depending 
38190 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
381a0 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
381b0 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20   callback to be 
381c0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  invoked..**.** {
381d0 48 31 32 39 38 33 7d 20 54 68 65 20 74 68 69 72  H12983} The thir
381e0 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67  d and fourth arg
381f0 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61  uments to the ca
38200 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70  llback contain p
38210 6f 69 6e 74 65 72 73 0a 2a 2a 20 20 20 20 20 20  ointers.**      
38220 20 20 20 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d      to zero-term
38230 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
38240 69 6e 67 73 20 77 68 69 63 68 20 61 72 65 20 74  ings which are t
38250 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  he names of the.
38260 2a 2a 20 20 20 20 20 20 20 20 20 20 64 61 74 61  **          data
38270 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 74  base and table t
38280 68 61 74 20 69 73 20 62 65 69 6e 67 20 75 70 64  hat is being upd
38290 61 74 65 64 2e 0a 0a 2a 2a 20 7b 48 31 32 39 38  ated...** {H1298
382a0 35 7d 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  5} The final cal
382b0 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
382c0 69 73 20 74 68 65 20 72 6f 77 69 64 20 6f 66 20  is the rowid of 
382d0 74 68 65 20 72 6f 77 20 61 66 74 65 72 0a 2a 2a  the row after.**
382e0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63 68            the ch
382f0 61 6e 67 65 20 6f 63 63 75 72 73 2e 0a 2a 2f 0a  ange occurs..*/.
38300 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70  void *sqlite3_up
38310 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c  date_hook(.  sql
38320 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  ite3*, .  void(*
38330 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68  )(void *,int ,ch
38340 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20  ar const *,char 
38350 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f  const *,sqlite3_
38360 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a  int64),.  void*.
38370 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
38380 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
38390 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67  sable Shared Pag
383a0 65 72 20 43 61 63 68 65 20 7b 48 31 30 33 33 30  er Cache {H10330
383b0 7d 20 3c 53 33 30 39 30 30 3e 0a 2a 2a 20 4b 45  } <S30900>.** KE
383c0 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20  YWORDS: {shared 
383d0 63 61 63 68 65 7d 20 7b 73 68 61 72 65 64 20 63  cache} {shared c
383e0 61 63 68 65 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a  ache mode}.**.**
383f0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e   This routine en
38400 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
38410 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
38420 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
38430 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
38440 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  a data structure
38450 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62  s between [datab
38460 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c  ase connection |
38470 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a   connections].**
38480 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
38490 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69  abase. Sharing i
384a0 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
384b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
384c0 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65  e.** and disable
384d0 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
384e0 74 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a  t is false..**.*
384f0 2a 20 43 61 63 68 65 20 73 68 61 72 69 6e 67 20  * Cache sharing 
38500 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64  is enabled and d
38510 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65  isabled for an e
38520 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 20 7b  ntire process. {
38530 45 4e 44 7d 0a 2a 2a 20 54 68 69 73 20 69 73 20  END}.** This is 
38540 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53  a change as of S
38550 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
38560 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65  5.0. In prior ve
38570 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
38580 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73  ,.** sharing was
38590 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
385a0 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68  bled for each th
385b0 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e  read separately.
385c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68 65  .**.** The cache
385d0 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65   sharing mode se
385e0 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66  t by this interf
385f0 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20  ace effects all 
38600 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  subsequent.** ca
38610 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
38620 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
38630 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e  3_open_v2()], an
38640 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  d [sqlite3_open1
38650 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  6()]..** Existin
38660 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  g database conne
38670 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
38680 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20  use the sharing 
38690 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73  mode.** that was
386a0 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68   in effect at th
386b0 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65  e time they were
386c0 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 56   opened..**.** V
386d0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61  irtual tables ca
386e0 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69 74  nnot be used wit
386f0 68 20 61 20 73 68 61 72 65 64 20 63 61 63 68 65  h a shared cache
38700 2e 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a 2a  .  When shared.*
38710 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
38720 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ed, the [sqlite3
38730 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29  _create_module()
38740 5d 20 41 50 49 20 75 73 65 64 20 74 6f 20 72 65  ] API used to re
38750 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75 61  gister.** virtua
38760 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61 6c  l tables will al
38770 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20 65  ways return an e
38780 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  rror..**.** This
38790 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
387a0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20   [SQLITE_OK] if 
387b0 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73  shared cache was
387c0 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
387d0 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66  bled.** successf
387e0 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72  ully.  An [error
387f0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
38800 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
38810 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68 65  .** Shared cache
38820 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
38830 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69  default. But thi
38840 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69