/ Hex Artifact Content
Login

Artifact 85e159e1d634c84ddbf87481293d5b1d26e2d27b:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f  rve to make mino
03c0: 72 20 63 68 61 6e 67 65 73 20 69 66 0a 2a 2a 20  r changes if.** 
03d0: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20  experience from 
03e0: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64  use "in the wild
03f0: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63  " suggest such c
0400: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65  hanges are prude
0410: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66  nt..**.** The of
0420: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67  ficial C-languag
0430: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74  e API documentat
0440: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69  ion for SQLite i
0450: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f  s derived.** fro
0460: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68  m comments in th
0470: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66  is file.  This f
0480: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f  ile is the autho
0490: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a  ritative source.
04a0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65  ** on how SQLite
04b0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
04c0: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61  suppose to opera
04d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  te..**.** The na
04e0: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  me of this file 
04f0: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74  under configurat
0500: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69  ion management i
0510: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e  s "sqlite.h.in".
0520: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65  .** The makefile
0530: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f   makes some mino
0540: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69  r changes to thi
0550: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20  s file (such as 
0560: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65  inserting.** the
0570: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29   version number)
0580: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73   and changes its
0590: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65   name to "sqlite
05a0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20  3.h" as.** part 
05b0: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f  of the build pro
05c0: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 40 28 23 29  cess..**.** @(#)
05d0: 20 24 49 64 3a 20 73 71 6c 69 74 65 2e 68 2e 69   $Id: sqlite.h.i
05e0: 6e 2c 76 20 31 2e 34 31 33 20 32 30 30 38 2f 31  n,v 1.413 2008/1
05f0: 31 2f 31 33 20 31 34 3a 32 38 3a 32 39 20 64 61  1/13 14:28:29 da
0600: 6e 69 65 6c 6b 31 39 37 37 20 45 78 70 20 24 0a  nielk1977 Exp $.
0610: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
0620: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
0630: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0640: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0650: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0660: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0670: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0680: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0690: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
06a0: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
06b0: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
06c0: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
06d0: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06e0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06f0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
0700: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
0710: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
0720: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
0730: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0740: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0750: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0760: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0770: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0780: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0790: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
07a0: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
07b0: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
07c0: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
07d0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07e0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07f0: 69 6e 74 72 66 61 63 65 73 20 2d 20 74 68 65 79  intrfaces - they
0800: 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f 72   are support for
0810: 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f   backwards.** co
0820: 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79  mpatibility only
0830: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77  .  Application w
0840: 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65  riters should be
0850: 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65   aware that.** e
0860: 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65  xperimental inte
0870: 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a 65  rfaces are subje
0880: 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20  ct to change in 
0890: 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a  point releases..
08a0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72  **.** These macr
08b0: 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c  os used to resol
08c0: 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69  ve to various ki
08d0: 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20  nds of compiler 
08e0: 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f  magic that.** wo
08f0: 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61 72  uld generate war
0900: 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68  ning messages wh
0910: 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73 65  en they were use
0920: 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20  d.  But that.** 
0930: 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65  compiler magic e
0940: 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74 69  nded up generati
0950: 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72 79  ng such a flurry
0960: 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a   of bug reports.
0970: 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65 20  ** that we have 
0980: 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74  taken it all out
0990: 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74   and gone back t
09a0: 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a  o using simple.*
09b0: 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a  * noop macros..*
09c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
09d0: 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65 66  _DEPRECATED.#def
09e0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52  ine SQLITE_EXPER
09f0: 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45  IMENTAL../*.** E
0a00: 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d 62  nsure these symb
0a10: 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66  ols were not def
0a20: 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65  ined by some pre
0a30: 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c  vious header fil
0a40: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
0a50: 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e  ITE_VERSION.# un
0a60: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0a70: 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66  ON.#endif.#ifdef
0a80: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
0a90: 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53  NUMBER.# undef S
0aa0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0ab0: 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  MBER.#endif../*.
0ac0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
0ad0: 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72  pile-Time Librar
0ae0: 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72  y Version Number
0af0: 73 20 7b 48 31 30 30 31 30 7d 20 3c 53 36 30 31  s {H10010} <S601
0b00: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  00>.**.** The SQ
0b10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 61 6e 64  LITE_VERSION and
0b20: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
0b30: 4e 55 4d 42 45 52 20 23 64 65 66 69 6e 65 73 20  NUMBER #defines 
0b40: 69 6e 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  in.** the sqlite
0b50: 33 2e 68 20 66 69 6c 65 20 73 70 65 63 69 66 79  3.h file specify
0b60: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   the version of 
0b70: 53 51 4c 69 74 65 20 77 69 74 68 20 77 68 69 63  SQLite with whic
0b80: 68 0a 2a 2a 20 74 68 61 74 20 68 65 61 64 65 72  h.** that header
0b90: 20 66 69 6c 65 20 69 73 20 61 73 73 6f 63 69 61   file is associa
0ba0: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22  ted..**.** The "
0bb0: 76 65 72 73 69 6f 6e 22 20 6f 66 20 53 51 4c 69  version" of SQLi
0bc0: 74 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 6f  te is a string o
0bd0: 66 20 74 68 65 20 66 6f 72 6d 20 22 58 2e 59 2e  f the form "X.Y.
0be0: 5a 22 2e 0a 2a 2a 20 54 68 65 20 70 68 72 61 73  Z"..** The phras
0bf0: 65 20 22 61 6c 70 68 61 22 20 6f 72 20 22 62 65  e "alpha" or "be
0c00: 74 61 22 20 6d 69 67 68 74 20 62 65 20 61 70 70  ta" might be app
0c10: 65 6e 64 65 64 20 61 66 74 65 72 20 74 68 65 20  ended after the 
0c20: 5a 2e 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c 75  Z..** The X valu
0c30: 65 20 69 73 20 6d 61 6a 6f 72 20 76 65 72 73 69  e is major versi
0c40: 6f 6e 20 6e 75 6d 62 65 72 20 61 6c 77 61 79 73  on number always
0c50: 20 33 20 69 6e 20 53 51 4c 69 74 65 33 2e 0a 2a   3 in SQLite3..*
0c60: 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20 6f 6e  * The X value on
0c70: 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65 6e 20  ly changes when 
0c80: 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
0c90: 69 62 69 6c 69 74 79 20 69 73 0a 2a 2a 20 62 72  ibility is.** br
0ca0: 6f 6b 65 6e 20 61 6e 64 20 77 65 20 69 6e 74 65  oken and we inte
0cb0: 6e 64 20 74 6f 20 6e 65 76 65 72 20 62 72 65 61  nd to never brea
0cc0: 6b 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  k backwards comp
0cd0: 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 54 68  atibility..** Th
0ce0: 65 20 59 20 76 61 6c 75 65 20 69 73 20 74 68 65  e Y value is the
0cf0: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
0d00: 75 6d 62 65 72 20 61 6e 64 20 6f 6e 6c 79 20 63  umber and only c
0d10: 68 61 6e 67 65 73 20 77 68 65 6e 0a 2a 2a 20 74  hanges when.** t
0d20: 68 65 72 65 20 61 72 65 20 6d 61 6a 6f 72 20 66  here are major f
0d30: 65 61 74 75 72 65 20 65 6e 68 61 6e 63 65 6d 65  eature enhanceme
0d40: 6e 74 73 20 74 68 61 74 20 61 72 65 20 66 6f 72  nts that are for
0d50: 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 6c 65  wards compatible
0d60: 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 62 61 63 6b  .** but not back
0d70: 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 6c 65  wards compatible
0d80: 2e 0a 2a 2a 20 54 68 65 20 5a 20 76 61 6c 75 65  ..** The Z value
0d90: 20 69 73 20 74 68 65 20 72 65 6c 65 61 73 65 20   is the release 
0da0: 6e 75 6d 62 65 72 20 61 6e 64 20 69 73 20 69 6e  number and is in
0db0: 63 72 65 6d 65 6e 74 65 64 20 77 69 74 68 0a 2a  cremented with.*
0dc0: 2a 20 65 61 63 68 20 72 65 6c 65 61 73 65 20 62  * each release b
0dd0: 75 74 20 72 65 73 65 74 73 20 62 61 63 6b 20 74  ut resets back t
0de0: 6f 20 30 20 77 68 65 6e 65 76 65 72 20 59 20 69  o 0 whenever Y i
0df0: 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 2e 0a 2a  s incremented..*
0e00: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
0e10: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
0e20: 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
0e30: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
0e40: 6d 62 65 72 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  mber()]..**.** I
0e50: 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
0e60: 20 7b 48 31 30 30 31 31 7d 20 54 68 65 20 53 51   {H10011} The SQ
0e70: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 23 64 65  LITE_VERSION #de
0e80: 66 69 6e 65 20 69 6e 20 74 68 65 20 73 71 6c 69  fine in the sqli
0e90: 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c  te3.h header fil
0ea0: 65 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  e shall.**      
0eb0: 20 20 20 20 65 76 61 6c 75 61 74 65 20 74 6f 20      evaluate to 
0ec0: 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
0ed0: 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c   that is the SQL
0ee0: 69 74 65 20 76 65 72 73 69 6f 6e 0a 2a 2a 20 20  ite version.**  
0ef0: 20 20 20 20 20 20 20 20 77 69 74 68 20 77 68 69          with whi
0f00: 63 68 20 74 68 65 20 68 65 61 64 65 72 20 66 69  ch the header fi
0f10: 6c 65 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  le is associated
0f20: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 30 31 34 7d  ..**.** {H10014}
0f30: 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53   The SQLITE_VERS
0f40: 49 4f 4e 5f 4e 55 4d 42 45 52 20 23 64 65 66 69  ION_NUMBER #defi
0f50: 6e 65 20 73 68 61 6c 6c 20 72 65 73 6f 6c 76 65  ne shall resolve
0f60: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   to an integer.*
0f70: 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20  *          with 
0f80: 74 68 65 20 76 61 6c 75 65 20 28 58 2a 31 30 30  the value (X*100
0f90: 30 30 30 30 20 2b 20 59 2a 31 30 30 30 20 2b 20  0000 + Y*1000 + 
0fa0: 5a 29 20 77 68 65 72 65 20 58 2c 20 59 2c 20 61  Z) where X, Y, a
0fb0: 6e 64 20 5a 0a 2a 2a 20 20 20 20 20 20 20 20 20  nd Z.**         
0fc0: 20 61 72 65 20 74 68 65 20 6d 61 6a 6f 72 20 76   are the major v
0fd0: 65 72 73 69 6f 6e 2c 20 6d 69 6e 6f 72 20 76 65  ersion, minor ve
0fe0: 72 73 69 6f 6e 2c 20 61 6e 64 20 72 65 6c 65 61  rsion, and relea
0ff0: 73 65 20 6e 75 6d 62 65 72 2e 0a 2a 2f 0a 23 64  se number..*/.#d
1000: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52  efine SQLITE_VER
1010: 53 49 4f 4e 20 20 20 20 20 20 20 20 20 22 2d 2d  SION         "--
1020: 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20  VERS--".#define 
1030: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1040: 55 4d 42 45 52 20 20 2d 2d 56 45 52 53 49 4f 4e  UMBER  --VERSION
1050: 2d 4e 55 4d 42 45 52 2d 2d 0a 0a 2f 2a 0a 2a 2a  -NUMBER--../*.**
1060: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
1070: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
1080: 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 48 31 30  ion Numbers {H10
1090: 30 32 30 7d 20 3c 53 36 30 31 30 30 3e 0a 2a 2a  020} <S60100>.**
10a0: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
10b0: 65 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  e3_version.**.**
10c0: 20 54 68 65 73 65 20 66 65 61 74 75 72 65 73 20   These features 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 0a 2a 2a 20 61 6e 64 20 5b 53 51 4c  ION].** and [SQL
1110: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
1120: 45 52 5d 20 23 64 65 66 69 6e 65 73 20 69 6e 20  ER] #defines in 
1130: 74 68 65 20 68 65 61 64 65 72 2c 20 62 75 74 20  the header, but 
1140: 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  are associated.*
1150: 2a 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61  * with the libra
1160: 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  ry instead of th
1170: 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20  e header file.  
1180: 43 61 75 74 69 6f 75 73 20 70 72 6f 67 72 61 6d  Cautious program
1190: 6d 65 72 73 20 6d 69 67 68 74 0a 2a 2a 20 69 6e  mers might.** in
11a0: 63 6c 75 64 65 20 61 20 63 68 65 63 6b 20 69 6e  clude a check in
11b0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
11c0: 6f 6e 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  on to verify tha
11d0: 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62  t.** sqlite3_lib
11e0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
11f0: 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
1200: 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 5b 53 51  the value.** [SQ
1210: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1220: 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  BER]..**.** The 
1230: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1240: 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  on() function re
1250: 74 75 72 6e 73 20 74 68 65 20 73 61 6d 65 20 69  turns the same i
1260: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73  nformation as is
1270: 0a 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c 69 74  .** in the sqlit
1280: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1290: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
12a0: 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  he function is p
12b0: 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 75  rovided.** for u
12c0: 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65  se in DLLs since
12d0: 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c   DLL users usual
12e0: 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 64  ly do not have d
12f0: 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20  irect access to 
1300: 73 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61  string.** consta
1310: 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44  nts within the D
1320: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  LL..**.** INVARI
1330: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30  ANTS:.**.** {H10
1340: 30 32 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  021} The [sqlite
1350: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
1360: 62 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ber()] interface
1370: 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a   shall return.**
1380: 20 20 20 20 20 20 20 20 20 20 61 6e 20 69 6e 74            an int
1390: 65 67 65 72 20 65 71 75 61 6c 20 74 6f 20 5b 53  eger equal to [S
13a0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
13b0: 4d 42 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  MBER]..**.** {H1
13c0: 30 30 32 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  0022} The [sqlit
13d0: 65 33 5f 76 65 72 73 69 6f 6e 5d 20 73 74 72 69  e3_version] stri
13e0: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 73 68 61 6c  ng constant shal
13f0: 6c 20 63 6f 6e 74 61 69 6e 0a 2a 2a 20 20 20 20  l contain.**    
1400: 20 20 20 20 20 20 74 68 65 20 74 65 78 74 20 6f        the text o
1410: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  f the [SQLITE_VE
1420: 52 53 49 4f 4e 5d 20 73 74 72 69 6e 67 2e 0a 2a  RSION] string..*
1430: 2a 0a 2a 2a 20 7b 48 31 30 30 32 33 7d 20 54 68  *.** {H10023} Th
1440: 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  e [sqlite3_libve
1450: 72 73 69 6f 6e 28 29 5d 20 66 75 6e 63 74 69 6f  rsion()] functio
1460: 6e 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 0a 2a  n shall return.*
1470: 2a 20 20 20 20 20 20 20 20 20 20 61 20 70 6f 69  *          a poi
1480: 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
1490: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5d 20 73 74  ite3_version] st
14a0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 0a 2a  ring constant..*
14b0: 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  /.SQLITE_EXTERN 
14c0: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
14d0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f  e3_version[];.co
14e0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
14f0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69  3_libversion(voi
1500: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
1510: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
1520: 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  r(void);../*.** 
1530: 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54  CAPI3REF: Test T
1540: 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62  o See If The Lib
1550: 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61  rary Is Threadsa
1560: 66 65 20 7b 48 31 30 31 30 30 7d 20 3c 53 36 30  fe {H10100} <S60
1570: 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  100>.**.** SQLit
1580: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1590: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
15a0: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
15b0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
15c0: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
15d0: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
15e0: 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73   1 or 2, mutexes
15f0: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
1600: 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68  and SQLite is th
1610: 72 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20  readsafe.  When 
1620: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  the.** [SQLITE_T
1630: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1640: 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d   is 0, .** the m
1650: 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74  utexes are omitt
1660: 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65  ed.  Without the
1670: 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20   mutexes, it is 
1680: 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75  not safe.** to u
1690: 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72  se SQLite concur
16a0: 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65  rently from more
16b0: 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64   than one thread
16c0: 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67  ..**.** Enabling
16d0: 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20   mutexes incurs 
16e0: 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72  a measurable per
16f0: 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79  formance penalty
1700: 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64  ..** So if speed
1710: 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d   is of utmost im
1720: 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b  portance, it mak
1730: 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61  es sense to disa
1740: 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ble.** the mutex
1750: 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78  es.  But for max
1760: 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74  imum safety, mut
1770: 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65  exes should be e
1780: 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65 20 64  nabled..** The d
1790: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
17a0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
17b0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
17c0: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
17d0: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
17e0: 79 20 61 20 70 72 6f 67 72 61 6d 20 74 6f 20 6d  y a program to m
17f0: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
1800: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
1810: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
1820: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
1830: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
1840: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
1850: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
1860: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
1870: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
1880: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1890: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
18a0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
18b0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
18c0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
18d0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
18e0: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
18f0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
1900: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
1910: 44 53 41 46 45 3d 31 20 74 68 65 6e 20 6d 75 74  DSAFE=1 then mut
1920: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
1930: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
1940: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
1950: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
1960: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
1970: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
1980: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
1990: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
19a0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
19b0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
19c0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
19d0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
19e0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
19f0: 5d 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  ].  The return v
1a00: 61 6c 75 65 20 6f 66 20 74 68 69 73 20 66 75 6e  alue of this fun
1a10: 63 74 69 6f 6e 20 73 68 6f 77 73 0a 2a 2a 20 6f  ction shows.** o
1a20: 6e 6c 79 20 74 68 65 20 64 65 66 61 75 6c 74 20  nly the default 
1a30: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74  compile-time set
1a40: 74 69 6e 67 2c 20 6e 6f 74 20 61 6e 79 20 72 75  ting, not any ru
1a50: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 0a 2a  n-time changes.*
1a60: 2a 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e  * to that settin
1a70: 67 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  g..**.** See the
1a80: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1a90: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
1aa0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
1ab0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1ac0: 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1ad0: 0a 2a 2a 20 7b 48 31 30 31 30 31 7d 20 54 68 65  .** {H10101} The
1ae0: 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
1af0: 73 61 66 65 28 29 5d 20 66 75 6e 63 74 69 6f 6e  safe()] function
1b00: 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 7a 65   shall return ze
1b10: 72 6f 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20  ro if.**        
1b20: 20 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 53 51    and only if SQ
1b30: 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65  Lite was compile
1b40: 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20  d with mutexing 
1b50: 63 6f 64 65 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  code omitted..**
1b60: 0a 2a 2a 20 7b 48 31 30 31 30 32 7d 20 54 68 65  .** {H10102} The
1b70: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1b80: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
1b90: 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 66 75  threadsafe()] fu
1ba0: 6e 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20  nction.**       
1bb0: 20 20 20 73 68 61 6c 6c 20 72 65 6d 61 69 6e 20     shall remain 
1bc0: 74 68 65 20 73 61 6d 65 20 61 63 72 6f 73 73 20  the same across 
1bd0: 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
1be0: 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2f 0a  3_config()]..*/.
1bf0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
1c00: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
1c10: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
1c20: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
1c30: 6f 6e 20 48 61 6e 64 6c 65 20 7b 48 31 32 30 30  on Handle {H1200
1c40: 30 7d 20 3c 53 34 30 32 30 30 3e 0a 2a 2a 20 4b  0} <S40200>.** K
1c50: 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61  EYWORDS: {databa
1c60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b  se connection} {
1c70: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c80: 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68  ions}.**.** Each
1c90: 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74   open SQLite dat
1ca0: 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73 65  abase is represe
1cb0: 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65  nted by a pointe
1cc0: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
1cd0: 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75   of.** the opaqu
1ce0: 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65  e structure name
1cf0: 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74  d "sqlite3".  It
1d00: 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68   is useful to th
1d10: 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65  ink of an sqlite
1d20: 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20  3.** pointer as 
1d30: 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  an object.  The 
1d40: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1d50: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
1d60: 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  6()], and.** [sq
1d70: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1d80: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
1d90: 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73  its constructors
1da0: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  , and [sqlite3_c
1db0: 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74  lose()].** is it
1dc0: 73 20 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54  s destructor.  T
1dd0: 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74  here are many ot
1de0: 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 28  her interfaces (
1df0: 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69  such as.** [sqli
1e00: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1e10: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
1e20: 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
1e30: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1e40: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
1e50: 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65  to name but thre
1e60: 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68  e) that are meth
1e70: 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c  ods on an.** sql
1e80: 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ite3 object..*/.
1e90: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
1ea0: 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a  qlite3 sqlite3;.
1eb0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ec0: 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20   64-Bit Integer 
1ed0: 54 79 70 65 73 20 7b 48 31 30 32 30 30 7d 20 3c  Types {H10200} <
1ee0: 53 31 30 31 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S10110>.** KEYWO
1ef0: 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36  RDS: sqlite_int6
1f00: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a  4 sqlite_uint64.
1f10: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
1f20: 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d  ere is no cross-
1f30: 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20  platform way to 
1f40: 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69  specify 64-bit i
1f50: 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20  nteger types.** 
1f60: 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20  SQLite includes 
1f70: 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d  typedefs for 64-
1f80: 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75  bit signed and u
1f90: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73  nsigned integers
1fa0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1fb0: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
1fc0: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65  lite3_uint64 are
1fd0: 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
1fe0: 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e  ype definitions.
1ff0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69  .** The sqlite_i
2000: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2010: 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65  uint64 types are
2020: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
2030: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
2040: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a  atibility only..
2050: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2060: 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32 30 31 7d  :.**.** {H10201}
2070: 20 54 68 65 20 5b 73 71 6c 69 74 65 5f 69 6e 74   The [sqlite_int
2080: 36 34 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  64] and [sqlite3
2090: 5f 69 6e 74 36 34 5d 20 74 79 70 65 20 73 68 61  _int64] type sha
20a0: 6c 6c 20 73 70 65 63 69 66 79 0a 2a 2a 20 20 20  ll specify.**   
20b0: 20 20 20 20 20 20 20 61 20 36 34 2d 62 69 74 20         a 64-bit 
20c0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a  signed integer..
20d0: 2a 2a 0a 2a 2a 20 7b 48 31 30 32 30 32 7d 20 54  **.** {H10202} T
20e0: 68 65 20 5b 73 71 6c 69 74 65 5f 75 69 6e 74 36  he [sqlite_uint6
20f0: 34 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  4] and [sqlite3_
2100: 75 69 6e 74 36 34 5d 20 74 79 70 65 20 73 68 61  uint64] type sha
2110: 6c 6c 20 73 70 65 63 69 66 79 0a 2a 2a 20 20 20  ll specify.**   
2120: 20 20 20 20 20 20 20 61 20 36 34 2d 62 69 74 20         a 64-bit 
2130: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
2140: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
2150: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20  TE_INT64_TYPE.  
2160: 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49  typedef SQLITE_I
2170: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
2180: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
2190: 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54  f unsigned SQLIT
21a0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
21b0: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69  ite_uint64;.#eli
21c0: 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56  f defined(_MSC_V
21d0: 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f  ER) || defined(_
21e0: 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74  _BORLANDC__).  t
21f0: 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73  ypedef __int64 s
2200: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
2210: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2220: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  __int64 sqlite_u
2230: 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74  int64;.#else.  t
2240: 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67  ypedef long long
2250: 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36   int sqlite_int6
2260: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2270: 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20  igned long long 
2280: 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  int sqlite_uint6
2290: 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65  4;.#endif.typede
22a0: 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73  f sqlite_int64 s
22b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79  qlite3_int64;.ty
22c0: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e  pedef sqlite_uin
22d0: 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  t64 sqlite3_uint
22e0: 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f  64;../*.** If co
22f0: 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72  mpiling for a pr
2300: 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63  ocessor that lac
2310: 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  ks floating poin
2320: 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75  t support,.** su
2330: 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72  bstitute integer
2340: 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f   for floating-po
2350: 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  int..*/.#ifdef S
2360: 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54  QLITE_OMIT_FLOAT
2370: 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69  ING_POINT.# defi
2380: 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  ne double sqlite
2390: 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a  3_int64.#endif..
23a0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23b0: 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61  Closing A Databa
23c0: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48  se Connection {H
23d0: 31 32 30 31 30 7d 20 3c 53 33 30 31 30 30 3e 3c  12010} <S30100><
23e0: 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S40200>.**.** Th
23f0: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68  is routine is th
2400: 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  e destructor for
2410: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2420: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  bject..**.** App
2430: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
2440: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2450: 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61  ze | finalize] a
2460: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
2470: 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20  tements].** and 
2480: 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
2490: 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c  ose | close] all
24a0: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20   [BLOB handles] 
24b0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
24c0: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ** the [sqlite3]
24d0: 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f   object prior to
24e0: 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63   attempting to c
24f0: 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e  lose the object.
2500: 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
2510: 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 20 69 6e  _next_stmt()] in
2520: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
2530: 73 65 64 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c  sed to locate al
2540: 6c 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  l.** [prepared s
2550: 74 61 74 65 6d 65 6e 74 73 5d 20 61 73 73 6f 63  tatements] assoc
2560: 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61  iated with a [da
2570: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2580: 6e 5d 20 69 66 20 64 65 73 69 72 65 64 2e 0a 2a  n] if desired..*
2590: 2a 20 54 79 70 69 63 61 6c 20 63 6f 64 65 20 6d  * Typical code m
25a0: 69 67 68 74 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74  ight look like t
25b0: 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
25c0: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
25d0: 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
25e0: 74 6d 74 3b 0a 2a 2a 20 77 68 69 6c 65 28 20 28  tmt;.** while( (
25f0: 70 53 74 6d 74 20 3d 20 73 71 6c 69 74 65 33 5f  pStmt = sqlite3_
2600: 6e 65 78 74 5f 73 74 6d 74 28 64 62 2c 20 30 29  next_stmt(db, 0)
2610: 29 21 3d 30 20 29 7b 0a 2a 2a 20 26 6e 62 73 70  )!=0 ){.** &nbsp
2620: 3b 20 20 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  ;   sqlite3_fina
2630: 6c 69 7a 65 28 70 53 74 6d 74 29 3b 0a 2a 2a 20  lize(pStmt);.** 
2640: 7d 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  }.** </pre></blo
2650: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49  ckquote>.**.** I
2660: 66 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  f [sqlite3_close
2670: 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ()] is invoked w
2680: 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69  hile a transacti
2690: 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74  on is open,.** t
26a0: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  he transaction i
26b0: 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
26c0: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
26d0: 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
26e0: 2a 0a 2a 2a 20 7b 48 31 32 30 31 31 7d 20 41 20  *.** {H12011} A 
26f0: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
2700: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
2710: 65 28 43 29 5d 20 73 68 61 6c 6c 20 64 65 73 74  e(C)] shall dest
2720: 72 6f 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  roy the.**      
2730: 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
2740: 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74  nnection] object
2750: 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31   C..**.** {H1201
2760: 32 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  2} A successful 
2770: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2780: 5f 63 6c 6f 73 65 28 43 29 5d 20 73 68 61 6c 6c  _close(C)] shall
2790: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
27a0: 4b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 30 31 33  K..**.** {H12013
27b0: 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
27c0: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
27d0: 63 6c 6f 73 65 28 43 29 5d 20 73 68 61 6c 6c 20  close(C)] shall 
27e0: 72 65 6c 65 61 73 65 20 61 6c 6c 0a 2a 2a 20 20  release all.**  
27f0: 20 20 20 20 20 20 20 20 6d 65 6d 6f 72 79 20 61          memory a
2800: 6e 64 20 73 79 73 74 65 6d 20 72 65 73 6f 75 72  nd system resour
2810: 63 65 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  ces associated w
2820: 69 74 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ith [database co
2830: 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 20 20 20  nnection].**    
2840: 20 20 20 20 20 20 43 2e 0a 2a 2a 0a 2a 2a 20 7b        C..**.** {
2850: 48 31 32 30 31 34 7d 20 41 20 63 61 6c 6c 20 74  H12014} A call t
2860: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
2870: 28 43 29 5d 20 6f 6e 20 61 20 5b 64 61 74 61 62  (C)] on a [datab
2880: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2890: 43 20 74 68 61 74 0a 2a 2a 20 20 20 20 20 20 20  C that.**       
28a0: 20 20 20 68 61 73 20 6f 6e 65 20 6f 72 20 6d 6f     has one or mo
28b0: 72 65 20 6f 70 65 6e 20 5b 70 72 65 70 61 72 65  re open [prepare
28c0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 68  d statements] sh
28d0: 61 6c 6c 20 66 61 69 6c 20 77 69 74 68 0a 2a 2a  all fail with.**
28e0: 20 20 20 20 20 20 20 20 20 20 61 6e 20 5b 53 51            an [SQ
28f0: 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72  LITE_BUSY] error
2900: 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   code..**.** {H1
2910: 32 30 31 35 7d 20 41 20 63 61 6c 6c 20 74 6f 20  2015} A call to 
2920: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
2930: 29 5d 20 77 68 65 72 65 20 43 20 69 73 20 61 20  )] where C is a 
2940: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 73 68 61  NULL pointer sha
2950: 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  ll.**          b
2960: 65 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  e a harmless no-
2970: 6f 70 20 72 65 74 75 72 6e 69 6e 67 20 53 51 4c  op returning SQL
2980: 49 54 45 5f 4f 4b 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ITE_OK..**.** {H
2990: 31 32 30 31 39 7d 20 57 68 65 6e 20 5b 73 71 6c  12019} When [sql
29a0: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 69  ite3_close(C)] i
29b0: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 5b  s invoked on a [
29c0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
29d0: 69 6f 6e 5d 20 43 0a 2a 2a 20 20 20 20 20 20 20  ion] C.**       
29e0: 20 20 20 74 68 61 74 20 68 61 73 20 61 20 70 65     that has a pe
29f0: 6e 64 69 6e 67 20 74 72 61 6e 73 61 63 74 69 6f  nding transactio
2a00: 6e 2c 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  n, the transacti
2a10: 6f 6e 20 73 68 61 6c 6c 20 62 65 0a 2a 2a 20 20  on shall be.**  
2a20: 20 20 20 20 20 20 20 20 72 6f 6c 6c 65 64 20 62          rolled b
2a30: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  ack..**.** ASSUM
2a40: 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
2a50: 31 32 30 31 36 7d 20 54 68 65 20 43 20 70 61 72  12016} The C par
2a60: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2a70: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75 73  e3_close(C)] mus
2a80: 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55  t be either a NU
2a90: 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70  LL.**          p
2aa0: 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71  ointer or an [sq
2ab0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f  lite3] object po
2ac0: 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a  inter obtained.*
2ad0: 2a 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20  *          from 
2ae0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
2af0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
2b00: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20  6()], or.**     
2b10: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6f 70       [sqlite3_op
2b20: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f  en_v2()], and no
2b30: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f  t previously clo
2b40: 73 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  sed..*/.int sqli
2b50: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
2b60: 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  3 *);../*.** The
2b70: 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c   type for a call
2b80: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  back function..*
2b90: 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79  * This is legacy
2ba0: 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e   and deprecated.
2bb0: 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64    It is included
2bc0: 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a   for historical.
2bd0: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
2be0: 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75   and is not docu
2bf0: 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64  mented..*/.typed
2c00: 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33  ef int (*sqlite3
2c10: 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a  _callback)(void*
2c20: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61  ,int,char**, cha
2c30: 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  r**);../*.** CAP
2c40: 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20  I3REF: One-Step 
2c50: 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20  Query Execution 
2c60: 49 6e 74 65 72 66 61 63 65 20 7b 48 31 32 31 30  Interface {H1210
2c70: 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a  0} <S10000>.**.*
2c80: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78  * The sqlite3_ex
2c90: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ec() interface i
2ca0: 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 74 20 77  s a convenient w
2cb0: 61 79 20 6f 66 20 72 75 6e 6e 69 6e 67 20 6f 6e  ay of running on
2cc0: 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 53 51 4c  e or more.** SQL
2cd0: 20 73 74 61 74 65 6d 65 6e 74 73 20 77 69 74 68   statements with
2ce0: 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 77 72  out having to wr
2cf0: 69 74 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63  ite a lot of C c
2d00: 6f 64 65 2e 20 20 54 68 65 20 55 54 46 2d 38 20  ode.  The UTF-8 
2d10: 65 6e 63 6f 64 65 64 0a 2a 2a 20 53 51 4c 20 73  encoded.** SQL s
2d20: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 70 61  tatements are pa
2d30: 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 20 73  ssed in as the s
2d40: 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2d50: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
2d60: 29 2e 0a 2a 2a 20 54 68 65 20 73 74 61 74 65 6d  )..** The statem
2d70: 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74  ents are evaluat
2d80: 65 64 20 6f 6e 65 20 62 79 20 6f 6e 65 20 75 6e  ed one by one un
2d90: 74 69 6c 20 65 69 74 68 65 72 20 61 6e 20 65 72  til either an er
2da0: 72 6f 72 20 6f 72 0a 2a 2a 20 61 6e 20 69 6e 74  ror or.** an int
2db0: 65 72 72 75 70 74 20 69 73 20 65 6e 63 6f 75 6e  errupt is encoun
2dc0: 74 65 72 65 64 2c 20 6f 72 20 75 6e 74 69 6c 20  tered, or until 
2dd0: 74 68 65 79 20 61 72 65 20 61 6c 6c 20 64 6f 6e  they are all don
2de0: 65 2e 20 20 54 68 65 20 33 72 64 20 70 61 72 61  e.  The 3rd para
2df0: 6d 65 74 65 72 0a 2a 2a 20 69 73 20 61 6e 20 6f  meter.** is an o
2e00: 70 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b  ptional callback
2e10: 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
2e20: 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72   once for each r
2e30: 6f 77 20 6f 66 20 61 6e 79 20 71 75 65 72 79 0a  ow of any query.
2e40: 2a 2a 20 72 65 73 75 6c 74 73 20 70 72 6f 64 75  ** results produ
2e50: 63 65 64 20 62 79 20 74 68 65 20 53 51 4c 20 73  ced by the SQL s
2e60: 74 61 74 65 6d 65 6e 74 73 2e 20 20 54 68 65 20  tatements.  The 
2e70: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 65  5th parameter te
2e80: 6c 6c 73 20 77 68 65 72 65 0a 2a 2a 20 74 6f 20  lls where.** to 
2e90: 77 72 69 74 65 20 61 6e 79 20 65 72 72 6f 72 20  write any error 
2ea0: 6d 65 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20  messages..**.** 
2eb0: 54 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  The error messag
2ec0: 65 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68  e passed back th
2ed0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
2ee0: 72 61 6d 65 74 65 72 20 69 73 20 68 65 6c 64 0a  rameter is held.
2ef0: 2a 2a 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ** in memory obt
2f00: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2f10: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
2f20: 54 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72  To avoid a memor
2f30: 79 20 6c 65 61 6b 2c 0a 2a 2a 20 74 68 65 20 63  y leak,.** the c
2f40: 61 6c 6c 69 6e 67 20 61 70 70 6c 69 63 61 74 69  alling applicati
2f50: 6f 6e 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 5b  on should call [
2f60: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
2f70: 6f 6e 20 61 6e 79 20 65 72 72 6f 72 0a 2a 2a 20  on any error.** 
2f80: 6d 65 73 73 61 67 65 20 72 65 74 75 72 6e 65 64  message returned
2f90: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
2fa0: 20 70 61 72 61 6d 65 74 65 72 20 77 68 65 6e 20   parameter when 
2fb0: 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
2fc0: 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 65 72 72  using.** the err
2fd0: 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
2fe0: 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
2ff0: 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 32 6e  tement in the 2n
3000: 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  d parameter is N
3010: 55 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20  ULL or an empty 
3020: 73 74 72 69 6e 67 0a 2a 2a 20 6f 72 20 61 20 73  string.** or a s
3030: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
3040: 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65   only whitespace
3050: 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   and comments, t
3060: 68 65 6e 20 6e 6f 20 53 51 4c 0a 2a 2a 20 73 74  hen no SQL.** st
3070: 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61  atements are eva
3080: 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64  luated and the d
3090: 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 20 63  atabase is not c
30a0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  hanged..**.** Th
30b0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
30c0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d   interface is im
30d0: 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 74 65 72  plemented in ter
30e0: 6d 73 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ms of.** [sqlite
30f0: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
3100: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
3110: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
3120: 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
3130: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
3140: 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
3150: 6e 6f 74 68 69 6e 67 20 74 6f 20 74 68 65 20 64  nothing to the d
3160: 61 74 61 62 61 73 65 20 74 68 61 74 20 63 61 6e  atabase that can
3170: 6e 6f 74 20 62 65 20 64 6f 6e 65 0a 2a 2a 20 62  not be done.** b
3180: 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
3190: 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
31a0: 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20  e3_step()], and 
31b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31c0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  e()]..**.** INVA
31d0: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
31e0: 31 32 31 30 31 7d 20 41 20 73 75 63 63 65 73 73  12101} A success
31f0: 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
3200: 66 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  f [sqlite3_exec(
3210: 44 2c 53 2c 43 2c 41 2c 45 29 5d 0a 2a 2a 20 20  D,S,C,A,E)].**  
3220: 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 73 65          shall se
3230: 71 75 65 6e 74 69 61 6c 6c 79 20 65 76 61 6c 75  quentially evalu
3240: 61 74 65 20 61 6c 6c 20 6f 66 20 74 68 65 20 55  ate all of the U
3250: 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a  TF-8 encoded,.**
3260: 20 20 20 20 20 20 20 20 20 20 73 65 6d 69 63 6f            semico
3270: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
3280: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
3290: 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
32a0: 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
32b0: 73 74 72 69 6e 67 20 53 20 77 69 74 68 69 6e 20  string S within 
32c0: 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74  the context of t
32d0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
32e0: 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a 2a  nection] D..**.*
32f0: 2a 20 7b 48 31 32 31 30 32 7d 20 49 66 20 74 68  * {H12102} If th
3300: 65 20 53 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e S parameter to
3310: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44   [sqlite3_exec(D
3320: 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73 20 4e 55  ,S,C,A,E)] is NU
3330: 4c 4c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20  LL then.**      
3340: 20 20 20 20 74 68 65 20 61 63 74 69 6f 6e 73 20      the actions 
3350: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
3360: 20 73 68 61 6c 6c 20 62 65 20 74 68 65 20 73 61   shall be the sa
3370: 6d 65 20 61 73 20 69 66 20 74 68 65 0a 2a 2a 20  me as if the.** 
3380: 20 20 20 20 20 20 20 20 20 53 20 70 61 72 61 6d           S param
3390: 65 74 65 72 20 77 65 72 65 20 61 6e 20 65 6d 70  eter were an emp
33a0: 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ty string..**.**
33b0: 20 7b 48 31 32 31 30 34 7d 20 54 68 65 20 72 65   {H12104} The re
33c0: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73  turn value of [s
33d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73  qlite3_exec()] s
33e0: 68 61 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f  hall be [SQLITE_
33f0: 4f 4b 5d 20 69 66 20 61 6c 6c 0a 2a 2a 20 20 20  OK] if all.**   
3400: 20 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65         SQL state
3410: 6d 65 6e 74 73 20 72 75 6e 20 73 75 63 63 65 73  ments run succes
3420: 73 66 75 6c 6c 79 20 61 6e 64 20 74 6f 20 63 6f  sfully and to co
3430: 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
3440: 7b 48 31 32 31 30 35 7d 20 54 68 65 20 72 65 74  {H12105} The ret
3450: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  urn value of [sq
3460: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 73 68  lite3_exec()] sh
3470: 61 6c 6c 20 62 65 20 61 6e 20 61 70 70 72 6f 70  all be an approp
3480: 72 69 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  riate.**        
3490: 20 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f    non-zero [erro
34a0: 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 20 53  r code] if any S
34b0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69  QL statement fai
34c0: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 30  ls..**.** {H1210
34d0: 37 7d 20 49 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  7} If one or mor
34e0: 65 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61  e of the SQL sta
34f0: 74 65 6d 65 6e 74 73 20 68 61 6e 64 65 64 20 74  tements handed t
3500: 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  o [sqlite3_exec(
3510: 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  )].**          r
3520: 65 74 75 72 6e 20 72 65 73 75 6c 74 73 20 61 6e  eturn results an
3530: 64 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  d the 3rd parame
3540: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ter is not NULL,
3550: 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   then.**        
3560: 20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66    the callback f
3570: 75 6e 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65  unction specifie
3580: 64 20 62 79 20 74 68 65 20 33 72 64 20 70 61 72  d by the 3rd par
3590: 61 6d 65 74 65 72 20 73 68 61 6c 6c 20 62 65 0a  ameter shall be.
35a0: 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f  **          invo
35b0: 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  ked once for eac
35c0: 68 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e  h row of result.
35d0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 30 7d 20  .**.** {H12110} 
35e0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
35f0: 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65  returns a non-ze
3600: 72 6f 20 76 61 6c 75 65 20 74 68 65 6e 20 5b 73  ro value then [s
3610: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a 2a  qlite3_exec()].*
3620: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c  *          shall
3630: 20 61 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   abort the SQL s
3640: 74 61 74 65 6d 65 6e 74 20 69 74 20 69 73 20 63  tatement it is c
3650: 75 72 72 65 6e 74 6c 79 20 65 76 61 6c 75 61 74  urrently evaluat
3660: 69 6e 67 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ing,.**         
3670: 20 73 6b 69 70 20 61 6c 6c 20 73 75 62 73 65 71   skip all subseq
3680: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
3690: 6e 74 73 2c 20 61 6e 64 20 72 65 74 75 72 6e 20  nts, and return 
36a0: 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
36b0: 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 33 7d 20 54  **.** {H12113} T
36c0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  he [sqlite3_exec
36d0: 28 29 5d 20 72 6f 75 74 69 6e 65 20 73 68 61 6c  ()] routine shal
36e0: 6c 20 70 61 73 73 20 69 74 73 20 34 74 68 20 70  l pass its 4th p
36f0: 61 72 61 6d 65 74 65 72 20 74 68 72 6f 75 67 68  arameter through
3700: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20  .**          as 
3710: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3720: 72 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  r of the callbac
3730: 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 31 31 36  k..**.** {H12116
3740: 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  } The [sqlite3_e
3750: 78 65 63 28 29 5d 20 72 6f 75 74 69 6e 65 20 73  xec()] routine s
3760: 68 61 6c 6c 20 73 65 74 20 74 68 65 20 32 6e 64  hall set the 2nd
3770: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 69 74   parameter of it
3780: 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  s.**          ca
3790: 6c 6c 62 61 63 6b 20 74 6f 20 62 65 20 74 68 65  llback to be the
37a0: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
37b0: 6e 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  ns in the curren
37c0: 74 20 72 6f 77 20 6f 66 0a 2a 2a 20 20 20 20 20  t row of.**     
37d0: 20 20 20 20 20 72 65 73 75 6c 74 2e 0a 2a 2a 0a       result..**.
37e0: 2a 2a 20 7b 48 31 32 31 31 39 7d 20 54 68 65 20  ** {H12119} The 
37f0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3800: 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20 73   routine shall s
3810: 65 74 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  et the 3rd param
3820: 65 74 65 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20  eter of its.**  
3830: 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b          callback
3840: 20 74 6f 20 62 65 20 61 6e 20 61 72 72 61 79 20   to be an array 
3850: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
3860: 74 72 69 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74  trings holding t
3870: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 76  he.**          v
3880: 61 6c 75 65 73 20 66 6f 72 20 65 61 63 68 20 63  alues for each c
3890: 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72  olumn in the cur
38a0: 72 65 6e 74 20 72 65 73 75 6c 74 20 73 65 74 20  rent result set 
38b0: 72 6f 77 20 61 73 0a 2a 2a 20 20 20 20 20 20 20  row as.**       
38c0: 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d     obtained from
38d0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
38e0: 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
38f0: 7b 48 31 32 31 32 32 7d 20 54 68 65 20 5b 73 71  {H12122} The [sq
3900: 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 72 6f  lite3_exec()] ro
3910: 75 74 69 6e 65 20 73 68 61 6c 6c 20 73 65 74 20  utine shall set 
3920: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
3930: 72 20 6f 66 20 69 74 73 0a 2a 2a 20 20 20 20 20  r of its.**     
3940: 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 74 6f       callback to
3950: 20 62 65 20 61 6e 20 61 72 72 61 79 20 6f 66 20   be an array of 
3960: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
3970: 6e 67 73 20 68 6f 6c 64 69 6e 67 20 74 68 65 0a  ngs holding the.
3980: 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65  **          name
3990: 73 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  s of result colu
39a0: 6d 6e 73 20 61 73 20 6f 62 74 61 69 6e 65 64 20  mns as obtained 
39b0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
39c0: 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a  lumn_name()]..**
39d0: 0a 2a 2a 20 7b 48 31 32 31 32 35 7d 20 49 66 20  .** {H12125} If 
39e0: 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
39f0: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78  r to [sqlite3_ex
3a00: 65 63 28 29 5d 20 69 73 20 4e 55 4c 4c 20 74 68  ec()] is NULL th
3a10: 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  en.**          [
3a20: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3a30: 73 68 61 6c 6c 20 73 69 6c 65 6e 74 6c 79 20 64  shall silently d
3a40: 69 73 63 61 72 64 20 71 75 65 72 79 20 72 65 73  iscard query res
3a50: 75 6c 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ults..**.** {H12
3a60: 31 33 31 7d 20 49 66 20 61 6e 20 65 72 72 6f 72  131} If an error
3a70: 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 70 61   occurs while pa
3a80: 72 73 69 6e 67 20 6f 72 20 65 76 61 6c 75 61 74  rsing or evaluat
3a90: 69 6e 67 20 61 6e 79 20 6f 66 20 74 68 65 20 53  ing any of the S
3aa0: 51 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  QL.**          s
3ab0: 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
3ac0: 20 53 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20   S parameter of 
3ad0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c  [sqlite3_exec(D,
3ae0: 53 2c 43 2c 41 2c 45 29 5d 20 61 6e 64 20 69 66  S,C,A,E)] and if
3af0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
3b00: 20 45 20 70 61 72 61 6d 65 74 65 72 20 69 73 20   E parameter is 
3b10: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b  not NULL, then [
3b20: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3b30: 73 68 61 6c 6c 20 73 74 6f 72 65 0a 2a 2a 20 20  shall store.**  
3b40: 20 20 20 20 20 20 20 20 69 6e 20 2a 45 20 61 6e          in *E an
3b50: 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72   appropriate err
3b60: 6f 72 20 6d 65 73 73 61 67 65 20 77 72 69 74 74  or message writt
3b70: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
3b80: 62 74 61 69 6e 65 64 0a 2a 2a 20 20 20 20 20 20  btained.**      
3b90: 20 20 20 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65      from [sqlite
3ba0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a  3_malloc()]..**.
3bb0: 2a 2a 20 7b 48 31 32 31 33 34 7d 20 54 68 65 20  ** {H12134} The 
3bc0: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44 2c  [sqlite3_exec(D,
3bd0: 53 2c 43 2c 41 2c 45 29 5d 20 72 6f 75 74 69 6e  S,C,A,E)] routin
3be0: 65 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20  e shall set the 
3bf0: 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20  value of.**     
3c00: 20 20 20 20 20 2a 45 20 74 6f 20 4e 55 4c 4c 20       *E to NULL 
3c10: 69 66 20 45 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  if E is not NULL
3c20: 20 61 6e 64 20 74 68 65 72 65 20 61 72 65 20 6e   and there are n
3c30: 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a 2a 2a 20  o errors..**.** 
3c40: 7b 48 31 32 31 33 37 7d 20 54 68 65 20 5b 73 71  {H12137} The [sq
3c50: 6c 69 74 65 33 5f 65 78 65 63 28 44 2c 53 2c 43  lite3_exec(D,S,C
3c60: 2c 41 2c 45 29 5d 20 66 75 6e 63 74 69 6f 6e 20  ,A,E)] function 
3c70: 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 5b 65  shall set the [e
3c80: 72 72 6f 72 20 63 6f 64 65 5d 0a 2a 2a 20 20 20  rror code].**   
3c90: 20 20 20 20 20 20 20 61 6e 64 20 6d 65 73 73 61         and messa
3ca0: 67 65 20 61 63 63 65 73 73 69 62 6c 65 20 76 69  ge accessible vi
3cb0: 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  a [sqlite3_errco
3cc0: 64 65 28 29 5d 2c 20 0a 2a 2a 20 20 20 20 20 20  de()], .**      
3cd0: 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 78 74      [sqlite3_ext
3ce0: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
3cf0: 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
3d00: 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
3d10: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  , and [sqlite3_e
3d20: 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  rrmsg16()]..**.*
3d30: 2a 20 7b 48 31 32 31 33 38 7d 20 49 66 20 74 68  * {H12138} If th
3d40: 65 20 53 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e S parameter to
3d50: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 44   [sqlite3_exec(D
3d60: 2c 53 2c 43 2c 41 2c 45 29 5d 20 69 73 20 4e 55  ,S,C,A,E)] is NU
3d70: 4c 4c 20 6f 72 20 61 6e 0a 2a 2a 20 20 20 20 20  LL or an.**     
3d80: 20 20 20 20 20 65 6d 70 74 79 20 73 74 72 69 6e       empty strin
3d90: 67 20 6f 72 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  g or contains no
3da0: 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
3db0: 20 77 68 69 74 65 73 70 61 63 65 2c 20 63 6f 6d   whitespace, com
3dc0: 6d 65 6e 74 73 2c 0a 2a 2a 20 20 20 20 20 20 20  ments,.**       
3dd0: 20 20 20 61 6e 64 2f 6f 72 20 73 65 6d 69 63 6f     and/or semico
3de0: 6c 6f 6e 73 2c 20 74 68 65 6e 20 72 65 73 75 6c  lons, then resul
3df0: 74 73 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 65  ts of [sqlite3_e
3e00: 72 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20  rrcode()],.**   
3e10: 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
3e20: 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
3e30: 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
3e40: 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
3e50: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
3e60: 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a  3_errmsg16()].**
3e70: 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20            shall 
3e80: 72 65 73 65 74 20 74 6f 20 69 6e 64 69 63 61 74  reset to indicat
3e90: 65 20 6e 6f 20 65 72 72 6f 72 73 2e 0a 2a 2a 0a  e no errors..**.
3ea0: 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a  ** ASSUMPTIONS:.
3eb0: 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34 31 7d 20 54  **.** {A12141} T
3ec0: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
3ed0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  er to [sqlite3_e
3ee0: 78 65 63 28 29 5d 20 6d 75 73 74 20 62 65 20 61  xec()] must be a
3ef0: 6e 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e  n valid and open
3f00: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 64 61  .**          [da
3f10: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3f20: 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31 34  n]..**.** {A1214
3f30: 32 7d 20 54 68 65 20 64 61 74 61 62 61 73 65 20  2} The database 
3f40: 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
3f50: 6e 6f 74 20 62 65 20 63 6c 6f 73 65 64 20 77 68  not be closed wh
3f60: 69 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ile.**          
3f70: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
3f80: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a   is running..**.
3f90: 2a 2a 20 7b 41 31 32 31 34 33 7d 20 54 68 65 20  ** {A12143} The 
3fa0: 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
3fb0: 20 73 68 6f 75 6c 64 20 75 73 65 20 5b 73 71 6c   should use [sql
3fc0: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 74 6f 20  ite3_free()] to 
3fd0: 66 72 65 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  free.**         
3fe0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
3ff0: 20 2a 65 72 72 6d 73 67 20 69 73 20 6c 65 66 74   *errmsg is left
4000: 20 70 6f 69 6e 74 69 6e 67 20 61 74 20 6f 6e 63   pointing at onc
4010: 65 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 20  e the error.**  
4020: 20 20 20 20 20 20 20 20 6d 65 73 73 61 67 65 20          message 
4030: 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65  is no longer nee
4040: 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 31  ded..**.** {A121
4050: 34 35 7d 20 54 68 65 20 53 51 4c 20 73 74 61 74  45} The SQL stat
4060: 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 20 74 68  ement text in th
4070: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
4080: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  to [sqlite3_exec
4090: 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
40a0: 6d 75 73 74 20 72 65 6d 61 69 6e 20 75 6e 63 68  must remain unch
40b0: 61 6e 67 65 64 20 77 68 69 6c 65 20 5b 73 71 6c  anged while [sql
40c0: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 69 73 20  ite3_exec()] is 
40d0: 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20  running..*/.int 
40e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20  sqlite3_exec(.  
40f0: 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20  sqlite3*,       
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e             /* An
4120: 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
4130: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
4140: 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  sql,            
4150: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4160: 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
4170: 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28  uated */.  int (
4180: 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a  *callback)(void*
4190: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72  ,int,char**,char
41a0: 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63  **),  /* Callbac
41b0: 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  k function */.  
41c0: 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20  void *,         
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73             /* 1s
41f0: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  t argument to ca
4200: 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72  llback */.  char
4210: 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20   **errmsg       
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4230: 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
4240: 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
4250: 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
4260: 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43  PI3REF: Result C
4270: 6f 64 65 73 20 7b 48 31 30 32 31 30 7d 20 3c 53  odes {H10210} <S
4280: 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  10700>.** KEYWOR
4290: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
42a0: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
42b0: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
42c0: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
42d0: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
42e0: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
42f0: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
4300: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
4310: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
4320: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
4330: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
4340: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
4350: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4360: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4370: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4380: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4390: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
43a0: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
43b0: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
43c0: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
43d0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
43e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
43f0: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
4400: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
4410: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
4420: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
4430: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
4440: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
4450: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
4460: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
4470: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
4480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
4490: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
44a0: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
44b0: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
44c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44d0: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
44e0: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
44f0: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
4500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4510: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
4520: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
4530: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
4540: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
4550: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
4560: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
4570: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
4580: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4590: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
45a0: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
45b0: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
45c0: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
45d0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
45e0: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
45f0: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4600: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4610: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4620: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4630: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
4640: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
4650: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
4660: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
4670: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
4680: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
4690: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
46a0: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
46b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
46c0: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
46d0: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
46e0: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
46f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4700: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4710: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4720: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4730: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
4740: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4750: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
4760: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
4770: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
4780: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
4790: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
47a0: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
47b0: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
47c0: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
47d0: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
47e0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
47f0: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4800: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4810: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4830: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
4840: 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20 44 61 74  /* NOT USED. Dat
4850: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
4860: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
4870: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
4880: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
4890: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
48a0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
48b0: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
48c0: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
48d0: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
48e0: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
48f0: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
4900: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
4910: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
4920: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
4930: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
4940: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
4950: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
4960: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
4970: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
4980: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
4990: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
49a0: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
49b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
49c0: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
49d0: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
49e0: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
49f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a00: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
4a10: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
4a20: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
4a30: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
4a40: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
4a50: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
4a60: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
4a70: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4a80: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
4a90: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
4aa0: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
4ab0: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
4ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
4ad0: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
4ae0: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
4af0: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
4b00: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
4b10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4b20: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
4b30: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
4b40: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
4b50: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
4b60: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20  ine SQLITE_ROW  
4b70: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73         100  /* s
4b80: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
4b90: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65  s another row re
4ba0: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ady */.#define S
4bb0: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20  QLITE_DONE      
4bc0: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65    101  /* sqlite
4bd0: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e  3_step() has fin
4be0: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20  ished executing 
4bf0: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72  */./* end-of-err
4c00: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a  or-codes */../*.
4c10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
4c20: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
4c30: 65 73 20 7b 48 31 30 32 32 30 7d 20 3c 53 31 30  es {H10220} <S10
4c40: 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  700>.** KEYWORDS
4c50: 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  : {extended erro
4c60: 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65  r code} {extende
4c70: 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a  d error codes}.*
4c80: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74  * KEYWORDS: {ext
4c90: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4ca0: 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73  e} {extended res
4cb0: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ult codes}.**.**
4cc0: 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20   In its default 
4cd0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53  configuration, S
4ce0: 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e  QLite API routin
4cf0: 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  es return one of
4d00: 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   26 integer.** [
4d10: 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75  SQLITE_OK | resu
4d20: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4d30: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4d40: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4d50: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4d60: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4d70: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4d80: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4d90: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4da0: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4db0: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4dc0: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4dd0: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4de0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4df0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4e00: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4e10: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4e20: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20  .3.8 and later) 
4e30: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4e40: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4e50: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
4e60: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
4e70: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
4e80: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
4e90: 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e  rrors. The exten
4ea0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4eb0: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20   are enabled or 
4ec0: 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61  disabled.** on a
4ed0: 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63 6f   per database co
4ee0: 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75  nnection basis u
4ef0: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
4f00: 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
4f10: 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50  sult_codes()] AP
4f20: 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66  I..**.** Some of
4f30: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65   the available e
4f40: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4f50: 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 20  odes are listed 
4f60: 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79  here..** One may
4f70: 20 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62   expect the numb
4f80: 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72  er of extended r
4f90: 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c  esult codes will
4fa0: 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76   be expand.** ov
4fb0: 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61  er time.  Softwa
4fc0: 72 65 20 74 68 61 74 20 75 73 65 73 20 65 78 74  re that uses ext
4fd0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4fe0: 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74  es should expect
4ff0: 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72  .** to see new r
5000: 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66  esult codes in f
5010: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
5020: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
5030: 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65  The SQLITE_OK re
5040: 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e  sult code will n
5050: 65 76 65 72 20 62 65 20 65 78 74 65 6e 64 65 64  ever be extended
5060: 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79  .  It will alway
5070: 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20  s.** be exactly 
5080: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  zero..**.** INVA
5090: 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
50a0: 31 30 32 32 33 7d 20 54 68 65 20 73 79 6d 62 6f  10223} The symbo
50b0: 6c 69 63 20 6e 61 6d 65 20 66 6f 72 20 61 6e 20  lic name for an 
50c0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
50d0: 63 6f 64 65 20 73 68 61 6c 6c 20 63 6f 6e 74 61  code shall conta
50e0: 69 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ins.**          
50f0: 61 20 72 65 6c 61 74 65 64 20 70 72 69 6d 61 72  a related primar
5100: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 61 73  y result code as
5110: 20 61 20 70 72 65 66 69 78 2e 0a 2a 2a 0a 2a 2a   a prefix..**.**
5120: 20 7b 48 31 30 32 32 34 7d 20 50 72 69 6d 61 72   {H10224} Primar
5130: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6e 61  y result code na
5140: 6d 65 73 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69  mes shall contai
5150: 6e 20 61 20 73 69 6e 67 6c 65 20 22 5f 22 20 63  n a single "_" c
5160: 68 61 72 61 63 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  haracter..**.** 
5170: 7b 48 31 30 32 32 35 7d 20 45 78 74 65 6e 64 65  {H10225} Extende
5180: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6e 61  d result code na
5190: 6d 65 73 20 73 68 61 6c 6c 20 63 6f 6e 74 61 69  mes shall contai
51a0: 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 22 5f  n two or more "_
51b0: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
51c0: 0a 2a 2a 20 7b 48 31 30 32 32 36 7d 20 54 68 65  .** {H10226} The
51d0: 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 6f   numeric value o
51e0: 66 20 61 6e 20 65 78 74 65 6e 64 65 64 20 72 65  f an extended re
51f0: 73 75 6c 74 20 63 6f 64 65 20 73 68 61 6c 6c 20  sult code shall 
5200: 63 6f 6e 74 61 69 6e 20 74 68 65 0a 2a 2a 20 20  contain the.**  
5210: 20 20 20 20 20 20 20 20 6e 75 6d 65 72 69 63 20          numeric 
5220: 76 61 6c 75 65 20 6f 66 20 69 74 73 20 63 6f 72  value of its cor
5230: 72 65 73 70 6f 6e 64 69 6e 67 20 70 72 69 6d 61  responding prima
5240: 72 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 69  ry result code i
5250: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74  n.**          it
5260: 73 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  s least signific
5270: 61 6e 74 20 38 20 62 69 74 73 2e 0a 2a 2f 0a 23  ant 8 bits..*/.#
5280: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5290: 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20  ERR_READ        
52a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
52b0: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ERR | (1<<8)).#d
52c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
52d0: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20  RR_SHORT_READ   
52e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
52f0: 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RR | (2<<8)).#de
5300: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5310: 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20  R_WRITE         
5320: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5330: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  R | (3<<8)).#def
5340: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5350: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  _FSYNC          
5360: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5370: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
5380: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5390: 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  DIR_FSYNC       
53a0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53b0: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
53c0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54  e SQLITE_IOERR_T
53d0: 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20  RUNCATE         
53e0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
53f0: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
5400: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
5410: 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20  TAT             
5420: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5430: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
5440: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c  SQLITE_IOERR_UNL
5450: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
5460: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5470: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
5480: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f  QLITE_IOERR_RDLO
5490: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
54a0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39  QLITE_IOERR | (9
54b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
54c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
54d0: 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  E            (SQ
54e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30  LITE_IOERR | (10
54f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5500: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
5510: 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ED           (SQ
5520: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31  LITE_IOERR | (11
5530: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5540: 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d  LITE_IOERR_NOMEM
5550: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5560: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32  LITE_IOERR | (12
5570: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5580: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53  LITE_IOERR_ACCES
5590: 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  S            (SQ
55a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33  LITE_IOERR | (13
55b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
55c0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b  LITE_IOERR_CHECK
55d0: 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51  RESERVEDLOCK (SQ
55e0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34  LITE_IOERR | (14
55f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5600: 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20  LITE_IOERR_LOCK 
5610: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5620: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35  LITE_IOERR | (15
5630: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
5640: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
5650: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
5660: 74 69 6f 6e 73 20 7b 48 31 30 32 33 30 7d 20 3c  tions {H10230} <
5670: 48 31 31 31 32 30 3e 20 3c 48 31 32 37 30 30 3e  H11120> <H12700>
5680: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74  .**.** These bit
5690: 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65   values are inte
56a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
56b0: 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d  the.** 3rd param
56c0: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
56d0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
56e0: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a  interface and.**
56f0: 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61   in the 4th para
5700: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70  meter to the xOp
5710: 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  en method of the
5720: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
5730: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
5740: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5750: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5760: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
5770: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5780: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5790: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
57a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
57b0: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
57c0: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
57d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
57e0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
57f0: 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65    0x00000008.#de
5800: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5810: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
5820: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
5830: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5840: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
5850: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
5860: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5870: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
5880: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
5890: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
58a0: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
58b0: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
58c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
58d0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
58e0: 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65    0x00000800.#de
58f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5900: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
5910: 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 65    0x00001000.#de
5920: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5930: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
5940: 20 20 30 78 30 30 30 30 32 30 30 30 0a 23 64 65    0x00002000.#de
5950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5960: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
5970: 20 20 30 78 30 30 30 30 34 30 30 30 0a 23 64 65    0x00004000.#de
5980: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5990: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
59a0: 20 20 30 78 30 30 30 30 38 30 30 30 0a 23 64 65    0x00008000.#de
59b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
59c0: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
59d0: 20 20 30 78 30 30 30 31 30 30 30 30 0a 0a 2f 2a    0x00010000../*
59e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
59f0: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
5a00: 74 69 63 73 20 7b 48 31 30 32 34 30 7d 20 3c 48  tics {H10240} <H
5a10: 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  11120>.**.** The
5a20: 20 78 44 65 76 69 63 65 43 61 70 61 62 69 6c 69   xDeviceCapabili
5a30: 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ties method of t
5a40: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
5a50: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
5a60: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  t returns an int
5a70: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20  eger which is a 
5a80: 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68  vector of the th
5a90: 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65  ese.** bit value
5aa0: 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f  s expressing I/O
5ab0: 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73   characteristics
5ac0: 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f   of the mass sto
5ad0: 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74  rage.** device t
5ae0: 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69  hat holds the fi
5af0: 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  le that the [sql
5b00: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
5b10: 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a  .** refers to..*
5b20: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
5b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
5b40: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
5b50: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
5b60: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
5b70: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
5b80: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
5b90: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
5ba0: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
5bb0: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
5bc0: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
5bd0: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
5be0: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
5bf0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
5c00: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
5c10: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
5c20: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
5c30: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
5c40: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
5c50: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
5c60: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
5c70: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
5c80: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
5c90: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
5ca0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
5cb0: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
5cc0: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
5cd0: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
5ce0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5cf0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
5d00: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
5d10: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
5d20: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
5d30: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
5d40: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
5d50: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23  o xWrite()..*/.#
5d60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5d70: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
5d80: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
5d90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5da0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
5db0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23      0x00000002.#
5dc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5dd0: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20  CAP_ATOMIC1K    
5de0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
5df0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5e00: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20  CAP_ATOMIC2K    
5e10: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
5e20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5e30: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
5e40: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
5e50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5e60: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
5e70: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23      0x00000020.#
5e80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5e90: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20  CAP_ATOMIC16K   
5ea0: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
5eb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5ec0: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
5ed0: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
5ee0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5ef0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
5f00: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
5f10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5f20: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
5f30: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23      0x00000200.#
5f40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5f50: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20  CAP_SEQUENTIAL  
5f60: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 0a      0x00000400..
5f70: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
5f80: 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76  File Locking Lev
5f90: 65 6c 73 20 7b 48 31 30 32 35 30 7d 20 3c 48 31  els {H10250} <H1
5fa0: 31 31 32 30 3e 20 3c 48 31 31 33 31 30 3e 0a 2a  1120> <H11310>.*
5fb0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
5fc0: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
5fd0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
5fe0: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
5ff0: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
6000: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
6010: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
6020: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
6030: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
6040: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6050: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
6060: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
6070: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
6080: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
6090: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
60a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
60b0: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
60c0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
60d0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
60e0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
60f0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6100: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
6110: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
6120: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
6130: 20 46 6c 61 67 73 20 7b 48 31 30 32 36 30 7d 20   Flags {H10260} 
6140: 3c 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 57  <H11120>.**.** W
6150: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
6160: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
6170: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
6180: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6190: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
61a0: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
61b0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
61c0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
61d0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
61e0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
61f0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
6200: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
6210: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
6220: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
6230: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
6240: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
6250: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
6260: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
6270: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
6280: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 54  ot be flushed. T
6290: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
62a0: 4f 52 4d 41 4c 20 66 6c 61 67 20 6d 65 61 6e 73  ORMAL flag means
62b0: 0a 2a 2a 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61  .** to use norma
62c0: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74  l fsync() semant
62d0: 69 63 73 2e 20 54 68 65 20 53 51 4c 49 54 45 5f  ics. The SQLITE_
62e0: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d  SYNC_FULL flag m
62f0: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
6300: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
6310: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
6320: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64  f fsync()..*/.#d
6330: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
6340: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20  C_NORMAL        
6350: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0x00002.#define 
6360: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6370: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6380: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
6390: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20  _SYNC_DATAONLY  
63a0: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a      0x00010../*.
63b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
63c0: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
63d0: 69 6c 65 20 48 61 6e 64 6c 65 20 7b 48 31 31 31  ile Handle {H111
63e0: 31 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a  10} <S20110>.**.
63f0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
6400: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
6410: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
6420: 69 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a  ile in the OS.**
6430: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
6440: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
6450: 20 69 6e 74 65 72 66 61 63 65 20 69 6d 70 6c 65   interface imple
6460: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
6470: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
6480: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
6490: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
64a0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
64b0: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
64c0: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
64d0: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
64e0: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
64f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6500: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
6510: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
6520: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
6530: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
6540: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
6550: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
6560: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
6570: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
6580: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
6590: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
65a0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
65b0: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
65c0: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
65d0: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
65e0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
65f0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
6600: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
6610: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20   Methods Object 
6620: 7b 48 31 31 31 32 30 7d 20 3c 53 32 30 31 31 30  {H11120} <S20110
6630: 3e 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69  >.**.** Every fi
6640: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65  le opened by the
6650: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
6660: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75  Open method popu
6670: 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c  lates an.** [sql
6680: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
6690: 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d  t (or, more comm
66a0: 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73  only, a subclass
66b0: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
66c0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
66d0: 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
66e0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
66f0: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a  of this object..
6700: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64  ** This object d
6710: 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f  efines the metho
6720: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f  ds used to perfo
6730: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61  rm various opera
6740: 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74  tions.** against
6750: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72   the open file r
6760: 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68  epresented by th
6770: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
6780: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54   object..**.** T
6790: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
67a0: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62  t to xSync may b
67b0: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  e one of [SQLITE
67c0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72  _SYNC_NORMAL] or
67d0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  .** [SQLITE_SYNC
67e0: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72  _FULL].  The fir
67f0: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65  st choice is the
6800: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e   normal fsync().
6810: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
6820: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f  hoice is a Mac O
6830: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
6840: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  nc.  The [SQLITE
6850: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a  _SYNC_DATAONLY].
6860: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f  ** flag may be O
6870: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61  Red in to indica
6880: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
6890: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
68a0: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73  e.** and not its
68b0: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20   inode needs to 
68c0: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a  be synced..**.**
68d0: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
68e0: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
68f0: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
6900: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
6910: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6920: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
6930: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6940: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
6950: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
6960: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
6970: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
6980: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
6990: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
69a0: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
69b0: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
69c0: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
69d0: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
69e0: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
69f0: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b  k..** The xCheck
6a00: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d  ReservedLock() m
6a10: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65  ethod checks whe
6a20: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73  ther any databas
6a30: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a  e connection,.**
6a40: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20   either in this 
6a50: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f  process or in so
6a60: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  me other process
6a70: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52  , is holding a R
6a80: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
6a90: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
6aa0: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
6ab0: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
6ac0: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
6ad0: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
6ae0: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73  d false otherwis
6af0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69  e..**.** The xFi
6b00: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68  leControl() meth
6b10: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  od is a generic 
6b20: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
6b30: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20  llows custom.** 
6b40: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
6b50: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20  ons to directly 
6b60: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20  control an open 
6b70: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  file using the.*
6b80: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
6b90: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
6ba0: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  face.  The secon
6bb0: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20  d "op" argument 
6bc0: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  is an.** integer
6bd0: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68   opcode.  The th
6be0: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
6bf0: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
6c00: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a  r intended to.**
6c10: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75   point to a stru
6c20: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
6c30: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
6c40: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
6c50: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
6c60: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
6c70: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
6c80: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
6c90: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
6ca0: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
6cb0: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
6cc0: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
6cd0: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
6ce0: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
6cf0: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
6d00: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
6d10: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
6d20: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
6d30: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
6d40: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
6d50: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
6d60: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
6d70: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65  erves all opcode
6d80: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  s less than 100 
6d90: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e  for its own use.
6da0: 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43  .** A [SQLITE_FC
6db0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20  NTL_LOCKSTATE | 
6dc0: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
6dd0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
6de0: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
6df0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
6e00: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
6e10: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
6e20: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
6e30: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
6e40: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
6e50: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
6e60: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
6e70: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
6e80: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
6e90: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
6ea0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
6eb0: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
6ec0: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
6ed0: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
6ee0: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
6ef0: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
6f00: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
6f10: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
6f20: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
6f30: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
6f40: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
6f50: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
6f60: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
6f70: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
6f80: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
6f90: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
6fa0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
6fb0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6fc0: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
6fd0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
6fe0: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
6ff0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7000: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
7010: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7020: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
7030: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7040: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
7050: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7060: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
7070: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7080: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
7090: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
70a0: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
70b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
70c0: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
70d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
70e0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
70f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7100: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
7110: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
7120: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
7130: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
7140: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
7150: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
7160: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
7170: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
7180: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
7190: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
71a0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
71b0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
71c0: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
71d0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
71e0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
71f0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
7200: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
7210: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
7220: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
7230: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
7240: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
7250: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
7260: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
7270: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
7280: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
7290: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
72a0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
72b0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
72c0: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
72d0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
72e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
72f0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
7300: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
7310: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
7320: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
7330: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
7340: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
7350: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
7360: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
7370: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
7380: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
7390: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
73a0: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
73b0: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
73c0: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
73d0: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
73e0: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
73f0: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
7400: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
7410: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
7420: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
7430: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
7440: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
7450: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
7460: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
7470: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
7480: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7490: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
74a0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
74b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
74c0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
74d0: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
74e0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
74f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
7500: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7510: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
7520: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
7530: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
7540: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
7550: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
7560: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
7570: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
7580: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
7590: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
75a0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
75b0: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
75c0: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
75d0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
75e0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
75f0: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
7600: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7610: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
7620: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
7630: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
7640: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
7650: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
7660: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
7670: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
7680: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
7690: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
76a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
76b0: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
76c0: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
76d0: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
76e0: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
76f0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
7700: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
7710: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
7720: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
7730: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
7740: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
7750: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
7760: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
7770: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7780: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
7790: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b 48  ntrol Opcodes {H
77a0: 31 31 33 31 30 7d 20 3c 53 33 30 38 30 30 3e 0a  11310} <S30800>.
77b0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
77c0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
77d0: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
77e0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
77f0: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
7800: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
7810: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
7820: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
7830: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
7840: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  .** interface..*
7850: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
7860: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
7870: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
7880: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
7890: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
78a0: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
78b0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
78c0: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
78d0: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
78e0: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
78f0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
7900: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
7910: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
7920: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
7930: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
7940: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
7950: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
7960: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
7970: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
7980: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
7990: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
79a0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
79b0: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
79c0: 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79  testing and only
79d0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
79e0: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
79f0: 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65  TE_TEST.** is de
7a00: 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e  fined..*/.#defin
7a10: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
7a20: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20  OCKSTATE        
7a30: 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  1../*.** CAPI3RE
7a40: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 20  F: Mutex Handle 
7a50: 7b 48 31 37 31 31 30 7d 20 3c 53 32 30 31 33 30  {H17110} <S20130
7a60: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65  >.**.** The mute
7a70: 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20  x module within 
7a80: 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b  SQLite defines [
7a90: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74  sqlite3_mutex] t
7aa0: 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72  o be an.** abstr
7ab0: 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d  act type for a m
7ac0: 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68  utex object.  Th
7ad0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65  e SQLite core ne
7ae0: 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20  ver looks.** at 
7af0: 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
7b00: 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  resentation of a
7b10: 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  n [sqlite3_mutex
7b20: 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64  ].  It only.** d
7b30: 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65  eals with pointe
7b40: 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  rs to the [sqlit
7b50: 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74  e3_mutex] object
7b60: 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20  ..**.** Mutexes 
7b70: 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
7b80: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
7b90: 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79  _alloc()]..*/.ty
7ba0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7bb0: 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74  ite3_mutex sqlit
7bc0: 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a  e3_mutex;../*.**
7bd0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
7be0: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 20 7b  terface Object {
7bf0: 48 31 31 31 34 30 7d 20 3c 53 32 30 31 30 30 3e  H11140} <S20100>
7c00: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
7c10: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ce of the sqlite
7c20: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66  3_vfs object def
7c30: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
7c40: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  ce between.** th
7c50: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  e SQLite core an
7c60: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
7c70: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
7c80: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
7c90: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
7ca0: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
7cb0: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
7cc0: 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a  ile system"..**.
7cd0: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
7ce0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
7cf0: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
7d00: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
7d10: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
7d20: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
7d30: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
7d40: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
7d50: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
7d60: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
7d70: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
7d80: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
7d90: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
7da0: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
7db0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
7dc0: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
7dd0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
7de0: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
7df0: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
7e00: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
7e10: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
7e20: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
7e30: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
7e40: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
7e50: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
7e60: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
7e70: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
7e80: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
7e90: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
7ea0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
7eb0: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
7ec0: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
7ed0: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
7ee0: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
7ef0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
7f00: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
7f10: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
7f20: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
7f30: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
7f40: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
7f50: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
7f60: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
7f70: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
7f80: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
7f90: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
7fa0: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
7fb0: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
7fc0: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
7fd0: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
7fe0: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
7ff0: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
8000: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
8010: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
8020: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
8030: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
8040: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
8050: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
8060: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
8070: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
8080: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
8090: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
80a0: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
80b0: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
80c0: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
80d0: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
80e0: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
80f0: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
8100: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
8110: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
8120: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
8130: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
8140: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
8150: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
8160: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
8170: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
8180: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
8190: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
81a0: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
81b0: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
81c0: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
81d0: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
81e0: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
81f0: 7b 48 31 31 31 34 31 7d 20 53 51 4c 69 74 65 20  {H11141} SQLite 
8200: 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74  will guarantee t
8210: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
8220: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
8230: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
8240: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
8250: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
8260: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
8270: 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 20 53 51  lPathname().  SQ
8280: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
8290: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
82a0: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
82b0: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
82c0: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
82d0: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
82e0: 65 64 2e 20 7b 45 4e 44 7d 20 20 42 65 63 61 75  ed. {END}  Becau
82f0: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
8300: 75 73 20 73 65 6e 74 65 6e 73 65 2c 0a 2a 2a 20  us sentense,.** 
8310: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
8320: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
8330: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
8340: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
8350: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
8360: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
8370: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
8380: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
8390: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
83a0: 65 74 65 72 20 69 73 20 78 4f 70 65 6e 20 69 73  eter is xOpen is
83b0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
83c0: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
83d0: 73 74 20 69 6e 76 69 74 65 20 69 74 73 20 6f 77  st invite its ow
83e0: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
83f0: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
8400: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
8410: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
8420: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
8430: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
8440: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
8450: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
8460: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
8470: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
8480: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
8490: 2a 20 7b 48 31 31 31 34 32 7d 20 54 68 65 20 66  * {H11142} The f
84a0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
84b0: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65   xOpen() include
84c0: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69  s all bits set i
84d0: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61  n.** the flags a
84e0: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
84f0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
8500: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   Or if [sqlite3_
8510: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  open()].** or [s
8520: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
8530: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
8540: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74  lags includes at
8550: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54   least.** [SQLIT
8560: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
8570: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
8580: 5f 43 52 45 41 54 45 5d 2e 20 7b 45 4e 44 7d 0a  _CREATE]. {END}.
8590: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
85a0: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
85b0: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
85c0: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
85d0: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
85e0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
85f0: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
8600: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
8610: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b   be set..**.** {
8620: 48 31 31 31 34 33 7d 20 53 51 4c 69 74 65 20 77  H11143} SQLite w
8630: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ill also add one
8640: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
8650: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
8660: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20  Open().** call, 
8670: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
8680: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70   object being op
8690: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ened:.**.** <ul>
86a0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
86b0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
86c0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
86d0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
86e0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
86f0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
8700: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
8710: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
8720: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
8730: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
8740: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
8750: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
8760: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
8770: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
8780: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
8790: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44  L].** </ul> {END
87a0: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  }.**.** The file
87b0: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
87c0: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
87d0: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
87e0: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
87f0: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
8800: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
8810: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
8820: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
8830: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
8840: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
8850: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
8860: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
8870: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
8880: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
8890: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
88a0: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
88b0: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
88c0: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
88d0: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
88e0: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
88f0: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
8900: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
8910: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
8920: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
8930: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
8940: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
8950: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
8960: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
8970: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
8980: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
8990: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
89a0: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
89b0: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
89c0: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
89d0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
89e0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
89f0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
8a00: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
8a10: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
8a20: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
8a30: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8a40: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
8a50: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
8a60: 7b 48 31 31 31 34 35 7d 20 54 68 65 20 5b 53 51  {H11145} The [SQ
8a70: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
8a80: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
8a90: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
8aa0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
8ab0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
8ac0: 73 65 64 2e 20 20 7b 48 31 31 31 34 36 7d 20 54  sed.  {H11146} T
8ad0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
8ae0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
8af0: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
8b00: 72 20 54 45 4d 50 20 20 64 61 74 61 62 61 73 65  r TEMP  database
8b10: 73 2c 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20  s, journals and 
8b20: 66 6f 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  for subjournals.
8b30: 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 37 7d 20  .**.** {H11147} 
8b40: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
8b50: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
8b60: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
8b70: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
8b80: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
8b90: 65 20 61 63 63 65 73 73 2e 20 20 54 68 69 73 20  e access.  This 
8ba0: 66 6c 61 67 20 69 73 20 73 65 74 20 66 6f 72 20  flag is set for 
8bb0: 61 6c 6c 20 66 69 6c 65 73 20 65 78 63 65 70 74  all files except
8bc0: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 6e  .** for the main
8bd0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
8be0: 2a 2a 0a 2a 2a 20 7b 48 31 31 31 34 38 7d 20 41  **.** {H11148} A
8bf0: 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65  t least szOsFile
8c00: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
8c10: 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   are allocated b
8c20: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68  y SQLite.** to h
8c30: 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65  old the  [sqlite
8c40: 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72  3_file] structur
8c50: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
8c60: 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  third.** argumen
8c70: 74 20 74 6f 20 78 4f 70 65 6e 2e 20 7b 45 4e 44  t to xOpen. {END
8c80: 7d 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  }  The xOpen met
8c90: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
8ca0: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
8cb0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
8cc0: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
8cd0: 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 0a 2a 2a  ill it in..**.**
8ce0: 20 7b 48 31 31 31 34 39 7d 20 54 68 65 20 66 6c   {H11149} The fl
8cf0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
8d00: 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65  xAccess() may be
8d10: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
8d20: 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65  EXISTS].** to te
8d30: 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74  st for the exist
8d40: 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20  ence of a file, 
8d50: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
8d60: 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a  S_READWRITE] to.
8d70: 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20  ** test whether 
8d80: 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  a file is readab
8d90: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c  le and writable,
8da0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
8db0: 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74  SS_READ].** to t
8dc0: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
8dd0: 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72  le is at least r
8de0: 65 61 64 61 62 6c 65 2e 20 7b 45 4e 44 7d 20 20  eadable. {END}  
8df0: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
8e00: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
8e10: 2a 2a 0a 2a 2a 20 7b 48 31 31 31 35 30 7d 20 53  **.** {H11150} S
8e20: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
8e30: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
8e40: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
8e50: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
8e60: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
8e70: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 7b  xFullPathname. {
8e80: 48 31 31 31 35 31 7d 20 54 68 65 20 65 78 61 63  H11151} The exac
8e90: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
8ea0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
8eb0: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
8ec0: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
8ed0: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 7b  both  methods. {
8ee0: 45 4e 44 7d 20 20 49 66 20 74 68 65 20 6f 75 74  END}  If the out
8ef0: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
8f00: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
8f10: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  h, [SQLITE_CANTO
8f20: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72  PEN] should be r
8f30: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74  eturned. Since t
8f40: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65  his is.** handle
8f50: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
8f60: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66  or by SQLite, vf
8f70: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
8f80: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
8f90: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20  r.** to prevent 
8fa0: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
8fb0: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20  mxPathname to a 
8fc0: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72  sufficiently lar
8fd0: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ge value..**.** 
8fe0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
8ff0: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61 6e 64  ), xSleep(), and
9000: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
9010: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
9020: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
9030: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
9040: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
9050: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
9060: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
9070: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
9080: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
9090: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
90a0: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
90b0: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
90c0: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
90d0: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
90e0: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
90f0: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
9100: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
9110: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
9120: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
9130: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
9140: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
9150: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
9160: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
9170: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
9180: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
9190: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
91a0: 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43 75 72  given.  The xCur
91b0: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
91c0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
91d0: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
91e0: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
91f0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 2e 0a   date and time..
9200: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
9210: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
9220: 6c 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63  lite3_vfs;.struc
9230: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
9240: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
9250: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
9260: 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
9270: 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20  number */.  int 
9280: 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20  szOsFile;       
9290: 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20       /* Size of 
92a0: 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74  subclassed sqlit
92b0: 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74  e3_file */.  int
92c0: 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20   mxPathname;    
92d0: 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
92e0: 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c   file pathname l
92f0: 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74  ength */.  sqlit
9300: 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20  e3_vfs *pNext;  
9310: 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69      /* Next regi
9320: 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20  stered VFS */.  
9330: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
9340: 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  e;       /* Name
9350: 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c   of this virtual
9360: 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a   file system */.
9370: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
9380: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f  ;          /* Po
9390: 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61  inter to applica
93a0: 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61  tion-specific da
93b0: 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f  ta */.  int (*xO
93c0: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
93d0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
93e0: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69  Name, sqlite3_fi
93f0: 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  le*,.           
9400: 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69      int flags, i
9410: 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a  nt *pOutFlags);.
9420: 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29    int (*xDelete)
9430: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
9440: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
9450: 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a  , int syncDir);.
9460: 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29    int (*xAccess)
9470: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
9480: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
9490: 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74  , int flags, int
94a0: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
94b0: 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d  t (*xFullPathnam
94c0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
94d0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
94e0: 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68  me, int nOut, ch
94f0: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69  ar *zOut);.  voi
9500: 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71  d *(*xDlOpen)(sq
9510: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
9520: 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
9530: 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  e);.  void (*xDl
9540: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
9550: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
9560: 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a  char *zErrMsg);.
9570: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 53 79 6d    void *(*xDlSym
9580: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
9590: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
95a0: 20 2a 7a 53 79 6d 62 6f 6c 29 3b 0a 20 20 76 6f   *zSymbol);.  vo
95b0: 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73  id (*xDlClose)(s
95c0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69  qlite3_vfs*, voi
95d0: 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61  d*);.  int (*xRa
95e0: 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65  ndomness)(sqlite
95f0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
9600: 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  e, char *zOut);.
9610: 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28    int (*xSleep)(
9620: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
9630: 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b  t microseconds);
9640: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
9650: 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  tTime)(sqlite3_v
9660: 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20  fs*, double*);. 
9670: 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45   int (*xGetLastE
9680: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
9690: 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29  s*, int, char *)
96a0: 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69 65 6c 64  ;.  /* New field
96b0: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
96c0: 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73  d in figure vers
96d0: 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
96e0: 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
96f0: 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
9700: 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
9710: 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ens. */.};../*.*
9720: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
9730: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
9740: 73 20 56 46 53 20 6d 65 74 68 6f 64 20 7b 48 31  s VFS method {H1
9750: 31 31 39 30 7d 20 3c 48 31 31 31 34 30 3e 0a 2a  1190} <H11140>.*
9760: 2a 0a 2a 2a 20 7b 48 31 31 31 39 31 7d 20 54 68  *.** {H11191} Th
9770: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
9780: 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65  tants can be use
9790: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70  d as the third p
97a0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
97b0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
97c0: 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  d of an [sqlite3
97d0: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45  _vfs] object. {E
97e0: 4e 44 7d 20 20 54 68 65 79 20 64 65 74 65 72 6d  ND}  They determ
97f0: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
9800: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
9810: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
9820: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
9830: 72 2e 0a 2a 2a 20 7b 48 31 31 31 39 32 7d 20 57  r..** {H11192} W
9840: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
9850: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41  S_EXISTS, the xA
9860: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
9870: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68  simply checks wh
9880: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65  ether the file e
9890: 78 69 73 74 73 2e 0a 2a 2a 20 7b 48 31 31 31 39  xists..** {H1119
98a0: 33 7d 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  3} With SQLITE_A
98b0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
98c0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
98d0: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
98e0: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
98f0: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
9900: 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a 2a 2a  and writable..**
9910: 20 7b 48 31 31 31 39 34 7d 20 57 69 74 68 20 53   {H11194} With S
9920: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
9930: 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  D, the xAccess m
9940: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
9950: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
9960: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f   is readable..*/
9970: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9980: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
9990: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
99a0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
99b0: 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  TE 1.#define SQL
99c0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
99d0: 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41       2../*.** CA
99e0: 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69  PI3REF: Initiali
99f0: 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ze The SQLite Li
9a00: 62 72 61 72 79 20 7b 48 31 30 31 33 30 7d 20 3c  brary {H10130} <
9a10: 53 32 30 30 30 30 3e 3c 53 33 30 31 30 30 3e 0a  S20000><S30100>.
9a20: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
9a30: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
9a40: 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a  outine initializ
9a50: 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  es the.** SQLite
9a60: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
9a70: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
9a80: 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61  ) routine.** dea
9a90: 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73  llocates any res
9aa0: 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65  ources that were
9ab0: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
9ac0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9ad0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  ()..**.** A call
9ae0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
9af0: 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22  ialize() is an "
9b00: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
9b10: 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20  if it is.** the 
9b20: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
9b30: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9b40: 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e  is invoked durin
9b50: 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
9b60: 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73  f.** the process
9b70: 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68  , or if it is th
9b80: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
9b90: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9ba0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
9bb0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
9bc0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
9bd0: 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 20 61 6e  down().  Only an
9be0: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
9bf0: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
9c00: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
9c10: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
9c20: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
9c30: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
9c40: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a  less no-ops..**.
9c50: 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74  ** Among other t
9c60: 68 69 6e 67 73 2c 20 73 71 6c 69 74 65 33 5f 69  hings, sqlite3_i
9c70: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 68 61 6c  nitialize() shal
9c80: 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  l invoke.** sqli
9c90: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
9ca0: 53 69 6d 69 6c 61 72 6c 79 2c 20 73 71 6c 69 74  Similarly, sqlit
9cb0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
9cc0: 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 20 73 71   shall invoke sq
9cd0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a  lite3_os_end()..
9ce0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
9cf0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
9d00: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
9d10: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
9d20: 63 63 65 73 73 2e 0a 2a 2a 20 49 66 20 66 6f 72  ccess..** If for
9d30: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
9d40: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9d50: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
9d60: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
9d70: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
9d80: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
9d90: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
9da0: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
9db0: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
9dc0: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
9dd0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
9de0: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
9df0: 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  OK]..**.** The s
9e00: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9e10: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
9e20: 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
9e30: 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
9e40: 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
9e50: 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
9e60: 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
9e70: 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
9e80: 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
9e90: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9ea0: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
9eb0: 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
9ec0: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
9ed0: 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
9ee0: 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
9ef0: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
9f00: 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
9f10: 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
9f20: 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
9f30: 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
9f40: 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
9f50: 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
9f60: 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 48  d.** already.  H
9f70: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
9f80: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
9f90: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
9fa0: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
9fb0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
9fc0: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
9fd0: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
9fe0: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
9ff0: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
a000: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
a010: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
a020: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
a030: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
a040: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
a050: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
a060: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
a070: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
a080: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
a090: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
a0a0: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
a0b0: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
a0c0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a0d0: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
a0e0: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
a0f0: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
a100: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
a110: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
a120: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
a130: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
a140: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
a150: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
a160: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
a170: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
a180: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
a190: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
a1a0: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
a1b0: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
a1c0: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
a1d0: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
a1e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
a1f0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
a200: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
a210: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
a220: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
a230: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
a240: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
a250: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
a260: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
a270: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
a280: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
a290: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
a2a0: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
a2b0: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
a2c0: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
a2d0: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
a2e0: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
a2f0: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
a300: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
a310: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
a320: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
a330: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
a340: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
a350: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
a360: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
a370: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
a380: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
a390: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
a3a0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
a3b0: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
a3c0: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
a3d0: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
a3e0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
a3f0: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
a400: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
a410: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
a420: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a430: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
a440: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
a450: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
a460: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
a470: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
a480: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
a490: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
a4a0: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
a4b0: 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
a4c0: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
a4d0: 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
a4e0: 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
a4f0: 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
a500: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
a510: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
a520: 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
a530: 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
a540: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
a550: 20 66 6f 72 20 75 6e 69 78 2c 20 77 69 6e 64 6f   for unix, windo
a560: 77 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a 2a 20  ws, or os/2..** 
a570: 57 68 65 6e 20 62 75 69 6c 74 20 66 6f 72 20 6f  When built for o
a580: 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 20 28  ther platforms (
a590: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
a5a0: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
a5b0: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
a5c0: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
a5d0: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
a5e0: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
a5f0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
a600: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
a610: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
a620: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
a630: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
a640: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
a650: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
a660: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
a670: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
a680: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
a690: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
a6a0: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
a6b0: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
a6c0: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
a6d0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
a6e0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
a6f0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
a700: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
a710: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
a720: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
a730: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
a740: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
a750: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
a760: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
a770: 61 72 79 20 7b 48 31 34 31 30 30 7d 20 3c 53 32  ary {H14100} <S2
a780: 30 30 30 30 3e 3c 53 33 30 32 30 30 3e 0a 2a 2a  0000><S30200>.**
a790: 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
a7a0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
a7b0: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
a7c0: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
a7d0: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
a7e0: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
a7f0: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
a800: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
a810: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
a820: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
a830: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
a840: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
a850: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
a860: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
a870: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
a880: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
a890: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
a8a0: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
a8b0: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
a8c0: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
a8d0: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
a8e0: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
a8f0: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
a900: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
a910: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
a920: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
a930: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
a940: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
a950: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
a960: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
a970: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
a980: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
a990: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
a9a0: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
a9b0: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
a9c0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a9d0: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
a9e0: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
a9f0: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
aa00: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
aa10: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
aa20: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
aa30: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
aa40: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
aa50: 5d 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  ]..** Note, howe
aa60: 76 65 72 2c 20 74 68 61 74 20 73 71 6c 69 74 65  ver, that sqlite
aa70: 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
aa80: 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
aa90: 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
aaa0: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
aab0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
aac0: 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
aad0: 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
aae0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
aaf0: 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
ab00: 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
ab10: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  ger.** [SQLITE_C
ab20: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
ab30: 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  AD | configurati
ab40: 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
ab50: 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
ab60: 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
ab70: 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
ab80: 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
ab90: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
aba0: 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
abb0: 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54  ng on the [SQLIT
abc0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
abd0: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72  HREAD | configur
abe0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
abf0: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
ac00: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68  gument..**.** Wh
ac10: 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69  en a configurati
ac20: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  on option is set
ac30: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
ac40: 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  () returns [SQLI
ac50: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 49 66 20 74 68  TE_OK]..** If th
ac60: 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
ac70: 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
ac80: 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
ac90: 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
aca0: 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
acb0: 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
acc0: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
acd0: 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
ace0: 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 30 33 7d  :.**.** {H14103}
acf0: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
ad00: 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
ad10: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 73  ite3_config()] s
ad20: 68 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20  hall return.**  
ad30: 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
ad40: 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31  OK]..**.** {H141
ad50: 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  06} The [sqlite3
ad60: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
ad70: 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75 72  face shall retur
ad80: 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
ad90: 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 66  ].**          if
ada0: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69   it is invoked i
adb0: 6e 20 62 65 74 77 65 65 6e 20 63 61 6c 6c 73 20  n between calls 
adc0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  to [sqlite3_init
add0: 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 0a 2a 2a  ialize()] and.**
ade0: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
adf0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
ae00: 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32 30 7d 20 41  **.** {H14120} A
ae10: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
ae20: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
ae30: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
ae40: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
ae50: 5d 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73  ]).**          s
ae60: 68 61 6c 6c 20 73 65 74 20 74 68 65 20 64 65 66  hall set the def
ae70: 61 75 6c 74 20 5b 74 68 72 65 61 64 69 6e 67 20  ault [threading 
ae80: 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d  mode] to Single-
ae90: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  thread..**.** {H
aea0: 31 34 31 32 33 7d 20 41 20 73 75 63 63 65 73 73  14123} A success
aeb0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
aec0: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
aed0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
aee0: 49 54 48 52 45 41 44 5d 29 0a 2a 2a 20 20 20 20  ITHREAD]).**    
aef0: 20 20 20 20 20 20 73 68 61 6c 6c 20 73 65 74 20        shall set 
af00: 74 68 65 20 64 65 66 61 75 6c 74 20 5b 74 68 72  the default [thr
af10: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
af20: 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 0a 2a 2a  Multi-thread..**
af30: 0a 2a 2a 20 7b 48 31 34 31 32 36 7d 20 41 20 73  .** {H14126} A s
af40: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
af50: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
af60: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
af70: 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 29 0a 2a  G_SERIALIZED]).*
af80: 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c  *          shall
af90: 20 73 65 74 20 74 68 65 20 64 65 66 61 75 6c 74   set the default
afa0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
afb0: 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
afc0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32 39 7d 20  .**.** {H14129} 
afd0: 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
afe0: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
aff0: 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
b000: 4e 46 49 47 5f 4d 55 54 45 58 5d 2c 58 29 0a 2a  NFIG_MUTEX],X).*
b010: 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72 65  *          where
b020: 20 58 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20   X is a pointer 
b030: 74 6f 20 61 6e 20 69 6e 69 74 69 61 6c 69 7a 65  to an initialize
b040: 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  d [sqlite3_mutex
b050: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 20 20 20  _methods].**    
b060: 20 20 20 20 20 20 6f 62 6a 65 63 74 20 73 68 61        object sha
b070: 6c 6c 20 63 61 75 73 65 20 61 6c 6c 20 73 75 62  ll cause all sub
b080: 73 65 71 75 65 6e 74 20 6d 75 74 65 78 20 6f 70  sequent mutex op
b090: 65 72 61 74 69 6f 6e 73 20 70 65 72 66 6f 72 6d  erations perform
b0a0: 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  ed.**          b
b0b0: 79 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20  y SQLite to use 
b0c0: 74 68 65 20 6d 75 74 65 78 20 6d 65 74 68 6f 64  the mutex method
b0d0: 73 20 74 68 61 74 20 77 65 72 65 20 70 72 65 73  s that were pres
b0e0: 65 6e 74 20 69 6e 20 58 0a 2a 2a 20 20 20 20 20  ent in X.**     
b0f0: 20 20 20 20 20 64 75 72 69 6e 67 20 74 68 65 20       during the 
b100: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
b110: 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
b120: 2a 20 7b 48 31 34 31 33 32 7d 20 41 20 73 75 63  * {H14132} A suc
b130: 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
b140: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
b150: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
b160: 47 45 54 4d 55 54 45 58 5d 2c 58 29 0a 2a 2a 20  GETMUTEX],X).** 
b170: 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20 58           where X
b180: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
b190: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74   an [sqlite3_mut
b1a0: 65 78 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  ex_methods] obje
b1b0: 63 74 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ct .**          
b1c0: 73 68 61 6c 6c 20 6f 76 65 72 77 72 69 74 65 20  shall overwrite 
b1d0: 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 5b  the content of [
b1e0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
b1f0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a  thods] object.**
b200: 20 20 20 20 20 20 20 20 20 20 77 69 74 68 20 74            with t
b210: 68 65 20 6d 75 74 65 78 20 6d 65 74 68 6f 64 73  he mutex methods
b220: 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75 73   currently in us
b230: 65 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  e by SQLite..**.
b240: 2a 2a 20 7b 48 31 34 31 33 35 7d 20 41 20 73 75  ** {H14135} A su
b250: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
b260: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
b270: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
b280: 5f 4d 41 4c 4c 4f 43 5d 2c 4d 29 0a 2a 2a 20 20  _MALLOC],M).**  
b290: 20 20 20 20 20 20 20 20 77 68 65 72 65 20 4d 20          where M 
b2a0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
b2b0: 61 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 5b  an initialized [
b2c0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
b2d0: 6f 64 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ods].**         
b2e0: 20 6f 62 6a 65 63 74 20 73 68 61 6c 6c 20 63 61   object shall ca
b2f0: 75 73 65 20 61 6c 6c 20 73 75 62 73 65 71 75 65  use all subseque
b300: 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  nt memory alloca
b310: 74 69 6f 6e 20 6f 70 65 72 61 74 69 6f 6e 73 0a  tion operations.
b320: 2a 2a 20 20 20 20 20 20 20 20 20 20 70 65 72 66  **          perf
b330: 6f 72 6d 65 64 20 62 79 20 53 51 4c 69 74 65 20  ormed by SQLite 
b340: 74 6f 20 75 73 65 20 74 68 65 20 6d 65 74 68 6f  to use the metho
b350: 64 73 20 74 68 61 74 20 77 65 72 65 20 70 72 65  ds that were pre
b360: 73 65 6e 74 20 69 6e 20 0a 2a 2a 20 20 20 20 20  sent in .**     
b370: 20 20 20 20 20 4d 20 64 75 72 69 6e 67 20 74 68       M during th
b380: 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  e call to [sqlit
b390: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
b3a0: 0a 2a 2a 20 7b 48 31 34 31 33 38 7d 20 41 20 73  .** {H14138} A s
b3b0: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
b3c0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
b3d0: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
b3e0: 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2c 4d 29 0a  G_GETMALLOC],M).
b3f0: 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72  **          wher
b400: 65 20 4d 20 69 73 20 61 20 70 6f 69 6e 74 65 72  e M is a pointer
b410: 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
b420: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  mem_methods] obj
b430: 65 63 74 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20  ect shall.**    
b440: 20 20 20 20 20 20 6f 76 65 72 77 72 69 74 65 20        overwrite 
b450: 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 5b  the content of [
b460: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
b470: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 77 69 74 68  ods] object with
b480: 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68   .**          th
b490: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
b4a0: 69 6f 6e 20 6d 65 74 68 6f 64 73 20 63 75 72 72  ion methods curr
b4b0: 65 6e 74 6c 79 20 69 6e 20 75 73 65 20 62 79 0a  ently in use by.
b4c0: 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 69  **          SQLi
b4d0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 34  te..**.** {H1414
b4e0: 31 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  1} A successful 
b4f0: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
b500: 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
b510: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
b520: 53 5d 2c 31 29 0a 2a 2a 20 20 20 20 20 20 20 20  S],1).**        
b530: 20 20 73 68 61 6c 6c 20 65 6e 61 62 6c 65 20 74    shall enable t
b540: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
b550: 74 69 6f 6e 20 73 74 61 74 75 73 20 63 6f 6c 6c  tion status coll
b560: 65 63 74 69 6f 6e 20 6c 6f 67 69 63 2e 0a 2a 2a  ection logic..**
b570: 0a 2a 2a 20 7b 48 31 34 31 34 34 7d 20 41 20 73  .** {H14144} A s
b580: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
b590: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
b5a0: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
b5b0: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 30 29 0a  G_MEMSTATUS],0).
b5c0: 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
b5d0: 6c 20 64 69 73 61 62 6c 65 20 74 68 65 20 6d 65  l disable the me
b5e0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
b5f0: 73 74 61 74 75 73 20 63 6f 6c 6c 65 63 74 69 6f  status collectio
b600: 6e 20 6c 6f 67 69 63 2e 0a 2a 2a 0a 2a 2a 20 7b  n logic..**.** {
b610: 48 31 34 31 34 37 7d 20 54 68 65 20 6d 65 6d 6f  H14147} The memo
b620: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
b630: 61 74 75 73 20 63 6f 6c 6c 65 63 74 69 6f 6e 20  atus collection 
b640: 6c 6f 67 69 63 20 73 68 61 6c 6c 20 62 65 0a 2a  logic shall be.*
b650: 2a 20 20 20 20 20 20 20 20 20 20 65 6e 61 62 6c  *          enabl
b660: 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
b670: 2a 0a 2a 2a 20 7b 48 31 34 31 35 30 7d 20 41 20  *.** {H14150} A 
b680: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
b690: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
b6a0: 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
b6b0: 49 47 5f 53 43 52 41 54 43 48 5d 2c 53 2c 5a 2c  IG_SCRATCH],S,Z,
b6c0: 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  N).**          w
b6d0: 68 65 72 65 20 5a 20 61 6e 64 20 4e 20 61 72 65  here Z and N are
b6e0: 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 69 6e   non-negative in
b6f0: 74 65 67 65 72 73 20 61 6e 64 20 0a 2a 2a 20 20  tegers and .**  
b700: 20 20 20 20 20 20 20 20 53 20 69 73 20 61 20 70          S is a p
b710: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 6c 69  ointer to an ali
b720: 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
b730: 65 72 20 6e 6f 74 20 6c 65 73 73 20 74 68 61 6e  er not less than
b740: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5a 2a 4e  .**          Z*N
b750: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 73   bytes in size s
b760: 68 61 6c 6c 20 63 61 75 73 65 20 53 20 74 6f 20  hall cause S to 
b770: 62 65 20 75 73 65 64 20 62 79 20 74 68 65 0a 2a  be used by the.*
b780: 2a 20 20 20 20 20 20 20 20 20 20 5b 73 63 72 61  *          [scra
b790: 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tch memory alloc
b7a0: 61 74 6f 72 5d 20 66 6f 72 20 61 73 20 6d 61 6e  ator] for as man
b7b0: 79 20 61 73 20 4e 20 73 69 6d 75 6c 61 74 61 6e  y as N simulatan
b7c0: 65 6f 75 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  eous.**         
b7d0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 65 61 63   allocations eac
b7e0: 68 20 6f 66 20 73 69 7a 65 20 5a 2e 0a 2a 2a 0a  h of size Z..**.
b7f0: 2a 2a 20 7b 48 31 34 31 35 33 7d 20 41 20 73 75  ** {H14153} A su
b800: 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
b810: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
b820: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
b830: 5f 53 43 52 41 54 43 48 5d 2c 53 2c 5a 2c 4e 29  _SCRATCH],S,Z,N)
b840: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65  .**          whe
b850: 72 65 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  re S is a NULL p
b860: 6f 69 6e 74 65 72 20 73 68 61 6c 6c 20 64 69 73  ointer shall dis
b870: 61 62 6c 65 20 74 68 65 0a 2a 2a 20 20 20 20 20  able the.**     
b880: 20 20 20 20 20 5b 73 63 72 61 74 63 68 20 6d 65       [scratch me
b890: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e  mory allocator].
b8a0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 35 36 7d 20  .**.** {H14156} 
b8b0: 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
b8c0: 6c 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  l to.**         
b8d0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
b8e0: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
b8f0: 5f 50 41 47 45 43 41 43 48 45 5d 2c 53 2c 5a 2c  _PAGECACHE],S,Z,
b900: 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  N).**          w
b910: 68 65 72 65 20 5a 20 61 6e 64 20 4e 20 61 72 65  here Z and N are
b920: 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 69 6e   non-negative in
b930: 74 65 67 65 72 73 20 61 6e 64 20 0a 2a 2a 20 20  tegers and .**  
b940: 20 20 20 20 20 20 20 20 53 20 69 73 20 61 20 70          S is a p
b950: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 6c 69  ointer to an ali
b960: 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
b970: 65 72 20 6e 6f 74 20 6c 65 73 73 20 74 68 61 6e  er not less than
b980: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5a 2a 4e  .**          Z*N
b990: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 73   bytes in size s
b9a0: 68 61 6c 6c 20 63 61 75 73 65 20 53 20 74 6f 20  hall cause S to 
b9b0: 62 65 20 75 73 65 64 20 62 79 20 74 68 65 0a 2a  be used by the.*
b9c0: 2a 20 20 20 20 20 20 20 20 20 20 5b 70 61 67 65  *          [page
b9d0: 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  cache memory all
b9e0: 6f 63 61 74 6f 72 5d 20 66 6f 72 20 61 73 20 6d  ocator] for as m
b9f0: 61 6e 79 20 61 73 20 4e 20 73 69 6d 75 6c 61 74  any as N simulat
ba00: 61 6e 65 6f 75 73 0a 2a 2a 20 20 20 20 20 20 20  aneous.**       
ba10: 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 65     allocations e
ba20: 61 63 68 20 6f 66 20 73 69 7a 65 20 5a 2e 0a 2a  ach of size Z..*
ba30: 2a 0a 2a 2a 20 7b 48 31 34 31 35 39 7d 20 41 20  *.** {H14159} A 
ba40: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
ba50: 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
ba60: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
ba70: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
ba80: 41 47 45 43 41 43 48 45 5d 2c 53 2c 5a 2c 4e 29  AGECACHE],S,Z,N)
ba90: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65  .**          whe
baa0: 72 65 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  re S is a NULL p
bab0: 6f 69 6e 74 65 72 20 73 68 61 6c 6c 20 64 69 73  ointer shall dis
bac0: 61 62 6c 65 20 74 68 65 0a 2a 2a 20 20 20 20 20  able the.**     
bad0: 20 20 20 20 20 5b 70 61 67 65 63 61 63 68 65 20       [pagecache 
bae0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
baf0: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 36 32  ]..**.** {H14162
bb00: 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
bb10: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
bb20: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
bb30: 43 4f 4e 46 49 47 5f 48 45 41 50 5d 2c 48 2c 5a  CONFIG_HEAP],H,Z
bb40: 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ,N).**          
bb50: 77 68 65 72 65 20 5a 20 61 6e 64 20 4e 20 61 72  where Z and N ar
bb60: 65 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 69  e non-negative i
bb70: 6e 74 65 67 65 72 73 20 61 6e 64 20 0a 2a 2a 20  ntegers and .** 
bb80: 20 20 20 20 20 20 20 20 20 48 20 69 73 20 61 20           H is a 
bb90: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 6c  pointer to an al
bba0: 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
bbb0: 66 65 72 20 6e 6f 74 20 6c 65 73 73 20 74 68 61  fer not less tha
bbc0: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5a 20  n.**          Z 
bbd0: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 73 68  bytes in size sh
bbe0: 61 6c 6c 20 65 6e 61 62 6c 65 20 74 68 65 20 5b  all enable the [
bbf0: 6d 65 6d 73 79 73 35 5d 20 6d 65 6d 6f 72 79 20  memsys5] memory 
bc00: 61 6c 6c 6f 63 61 74 6f 72 0a 2a 2a 20 20 20 20  allocator.**    
bc10: 20 20 20 20 20 20 61 6e 64 20 63 61 75 73 65 20        and cause 
bc20: 69 74 20 74 6f 20 75 73 65 20 62 75 66 66 65 72  it to use buffer
bc30: 20 53 20 61 73 20 69 74 73 20 6d 65 6d 6f 72 79   S as its memory
bc40: 20 73 6f 75 72 63 65 20 61 6e 64 20 74 6f 20 75   source and to u
bc50: 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  se.**          a
bc60: 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
bc70: 69 6f 6e 20 73 69 7a 65 20 6f 66 20 4e 2e 0a 2a  ion size of N..*
bc80: 2a 0a 2a 2a 20 7b 48 31 34 31 36 35 7d 20 41 20  *.** {H14165} A 
bc90: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
bca0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
bcb0: 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
bcc0: 49 47 5f 48 45 41 50 5d 2c 48 2c 5a 2c 4e 29 0a  IG_HEAP],H,Z,N).
bcd0: 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72  **          wher
bce0: 65 20 48 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  e H is a NULL po
bcf0: 69 6e 74 65 72 20 73 68 61 6c 6c 20 64 69 73 61  inter shall disa
bd00: 62 6c 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ble the.**      
bd10: 20 20 20 20 5b 6d 65 6d 73 79 73 35 5d 20 6d 65      [memsys5] me
bd20: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 0a  mory allocator..
bd30: 2a 2a 0a 2a 2a 20 7b 48 31 34 31 36 38 7d 20 41  **.** {H14168} A
bd40: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
bd50: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
bd60: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
bd70: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 5a  FIG_LOOKASIDE],Z
bd80: 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ,N).**          
bd90: 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20  shall cause the 
bda0: 64 65 66 61 75 6c 74 20 5b 6c 6f 6f 6b 61 73 69  default [lookasi
bdb0: 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
bdc0: 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
bdd0: 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  on.**          f
bde0: 6f 72 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65  or new [database
bdf0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 74 6f   connections] to
be00: 20 62 65 20 4e 20 73 6c 6f 74 73 20 6f 66 20 5a   be N slots of Z
be10: 20 62 79 74 65 73 20 65 61 63 68 2e 0a 2a 2f 0a   bytes each..*/.
be20: 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
be30: 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TAL int sqlite3_
be40: 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29  config(int, ...)
be50: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
be60: 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74  F: Configure dat
be70: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
be80: 73 20 20 7b 48 31 34 32 30 30 7d 20 3c 53 32 30  s  {H14200} <S20
be90: 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  000>.** EXPERIME
bea0: 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  NTAL.**.** The s
beb0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
bec0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
bed0: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
bee0: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
bef0: 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
bf00: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
bf10: 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
bf20: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
bf30: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
bf40: 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
bf50: 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
bf60: 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
bf70: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
bf80: 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
bf90: 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
bfa0: 61 72 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a  argument).  The.
bfb0: 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  ** sqlite3_db_co
bfc0: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
bfd0: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
bfe0: 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66  d immediately af
bff0: 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ter.** the datab
c000: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
c010: 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  s created using 
c020: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
c030: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ,.** [sqlite3_op
c040: 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c  en16()], or [sql
c050: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
c060: 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63    .**.** The sec
c070: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
c080: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
c090: 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
c0a0: 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  he.** configurat
c0b0: 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69 6e  ion verb - an in
c0c0: 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
c0d0: 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a 2a  indicates what.*
c0e0: 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  * aspect of the 
c0f0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c100: 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
c110: 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68  onfigured..** Th
c120: 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f  e only choice fo
c130: 72 20 74 68 69 73 20 76 61 6c 75 65 20 69 73 20  r this value is 
c140: 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
c150: 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20  _LOOKASIDE]..** 
c160: 4e 65 77 20 76 65 72 62 73 20 61 72 65 20 6c 69  New verbs are li
c170: 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65 64  kely to be added
c180: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
c190: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
c1a0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  * Additional arg
c1b0: 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e  uments depend on
c1c0: 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a   the verb..**.**
c1d0: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
c1e0: 2a 2a 20 7b 48 31 34 32 30 33 7d 20 41 20 63 61  ** {H14203} A ca
c1f0: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  ll to [sqlite3_d
c200: 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e  b_config(D,V,...
c210: 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  )] shall return 
c220: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 20  [SQLITE_OK].**  
c230: 20 20 20 20 20 20 20 20 69 66 20 61 6e 64 20 6f          if and o
c240: 6e 6c 79 20 69 66 20 74 68 65 20 63 61 6c 6c 20  nly if the call 
c250: 69 73 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a  is successful..*
c260: 2a 0a 2a 2a 20 7b 48 31 34 32 30 36 7d 20 49 66  *.** {H14206} If
c270: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 6c 6f   one or more slo
c280: 74 73 20 6f 66 20 74 68 65 20 5b 6c 6f 6f 6b 61  ts of the [looka
c290: 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
c2a0: 63 61 74 6f 72 5d 20 66 6f 72 0a 2a 2a 20 20 20  cator] for.**   
c2b0: 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
c2c0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 61   connection] D a
c2d0: 72 65 20 69 6e 20 75 73 65 2c 20 74 68 65 6e 20  re in use, then 
c2e0: 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20  a call to.**    
c2f0: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 64        [sqlite3_d
c300: 62 5f 63 6f 6e 66 69 67 5d 28 44 2c 5b 53 51 4c  b_config](D,[SQL
c310: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
c320: 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 73 68 61  KASIDE],...) sha
c330: 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  ll.**          f
c340: 61 69 6c 20 77 69 74 68 20 61 6e 20 5b 53 51 4c  ail with an [SQL
c350: 49 54 45 5f 42 55 53 59 5d 20 72 65 74 75 72 6e  ITE_BUSY] return
c360: 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   code..**.** {H1
c370: 34 32 30 39 7d 20 41 20 73 75 63 63 65 73 73 66  4209} A successf
c380: 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 20  ul call to .**  
c390: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
c3a0: 5f 64 62 5f 63 6f 6e 66 69 67 5d 28 44 2c 5b 53  _db_config](D,[S
c3b0: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
c3c0: 4f 4f 4b 41 53 49 44 45 5d 2c 42 2c 5a 2c 4e 29  OOKASIDE],B,Z,N)
c3d0: 20 77 68 65 72 65 0a 2a 2a 20 20 20 20 20 20 20   where.**       
c3e0: 20 20 20 44 20 69 73 20 61 6e 20 6f 70 65 6e 20     D is an open 
c3f0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c400: 74 69 6f 6e 5d 20 61 6e 64 20 5a 20 61 6e 64 20  tion] and Z and 
c410: 4e 20 61 72 65 20 70 6f 73 69 74 69 76 65 0a 2a  N are positive.*
c420: 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 67  *          integ
c430: 65 72 73 20 61 6e 64 20 42 20 69 73 20 61 6e 20  ers and B is an 
c440: 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 20 61  aligned buffer a
c450: 74 20 6c 65 61 73 74 20 5a 2a 4e 20 62 79 74 65  t least Z*N byte
c460: 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20 20 20 20  s in size.**    
c470: 20 20 20 20 20 20 73 68 61 6c 6c 20 63 61 75 73        shall caus
c480: 65 20 74 68 65 20 5b 6c 6f 6f 6b 61 73 69 64 65  e the [lookaside
c490: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
c4a0: 72 5d 20 66 6f 72 20 44 20 74 6f 20 75 73 65 20  r] for D to use 
c4b0: 62 75 66 66 65 72 20 42 20 0a 2a 2a 20 20 20 20  buffer B .**    
c4c0: 20 20 20 20 20 20 77 69 74 68 20 4e 20 73 6c 6f        with N slo
c4d0: 74 73 20 6f 66 20 5a 20 62 79 74 65 73 20 65 61  ts of Z bytes ea
c4e0: 63 68 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32 31  ch..**.** {H1421
c4f0: 32 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  2} A successful 
c500: 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 20 20 20 20  call to .**     
c510: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 64 62       [sqlite3_db
c520: 5f 63 6f 6e 66 69 67 5d 28 44 2c 5b 53 51 4c 49  _config](D,[SQLI
c530: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
c540: 41 53 49 44 45 5d 2c 42 2c 5a 2c 4e 29 20 77 68  ASIDE],B,Z,N) wh
c550: 65 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ere.**          
c560: 44 20 69 73 20 61 6e 20 6f 70 65 6e 20 5b 64 61  D is an open [da
c570: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
c580: 6e 5d 20 61 6e 64 20 5a 20 61 6e 64 20 4e 20 61  n] and Z and N a
c590: 72 65 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20  re positive.**  
c5a0: 20 20 20 20 20 20 20 20 69 6e 74 65 67 65 72 73          integers
c5b0: 20 61 6e 64 20 42 20 69 73 20 4e 55 4c 4c 20 70   and B is NULL p
c5c0: 6f 69 6e 74 65 72 20 73 68 61 6c 6c 20 63 61 75  ointer shall cau
c5d0: 73 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  se the.**       
c5e0: 20 20 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65     [lookaside me
c5f0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
c600: 66 6f 72 20 44 20 74 6f 20 61 20 6f 62 74 61 69  for D to a obtai
c610: 6e 20 5a 2a 4e 20 62 79 74 65 20 62 75 66 66 65  n Z*N byte buffe
c620: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72  r.**          fr
c630: 6f 6d 20 74 68 65 20 70 72 69 6d 61 72 79 20 6d  om the primary m
c640: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
c650: 61 6e 64 20 75 73 65 20 74 68 61 74 20 62 75 66  and use that buf
c660: 66 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  fer.**          
c670: 77 69 74 68 20 4e 20 6c 6f 6f 6b 61 73 69 64 65  with N lookaside
c680: 20 73 6c 6f 74 73 20 6f 66 20 5a 20 62 79 74 65   slots of Z byte
c690: 73 20 65 61 63 68 2e 0a 2a 2a 0a 2a 2a 20 7b 48  s each..**.** {H
c6a0: 31 34 32 31 35 7d 20 41 20 73 75 63 63 65 73 73  14215} A success
c6b0: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20  ful call to .** 
c6c0: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
c6d0: 33 5f 64 62 5f 63 6f 6e 66 69 67 5d 28 44 2c 5b  3_db_config](D,[
c6e0: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
c6f0: 4c 4f 4f 4b 41 53 49 44 45 5d 2c 42 2c 5a 2c 4e  LOOKASIDE],B,Z,N
c700: 29 20 77 68 65 72 65 0a 2a 2a 20 20 20 20 20 20  ) where.**      
c710: 20 20 20 20 44 20 69 73 20 61 6e 20 6f 70 65 6e      D is an open
c720: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
c730: 63 74 69 6f 6e 5d 20 61 6e 64 20 5a 20 61 6e 64  ction] and Z and
c740: 20 4e 20 61 72 65 20 7a 65 72 6f 20 73 68 61 6c   N are zero shal
c750: 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 69  l.**          di
c760: 73 61 62 6c 65 20 74 68 65 20 5b 6c 6f 6f 6b 61  sable the [looka
c770: 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
c780: 63 61 74 6f 72 5d 20 66 6f 72 20 44 2e 0a 2a 2a  cator] for D..**
c790: 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  .**.*/.SQLITE_EX
c7a0: 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73  PERIMENTAL int s
c7b0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
c7c0: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
c7d0: 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  p, ...);../*.** 
c7e0: 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
c7f0: 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74   Allocation Rout
c800: 69 6e 65 73 20 7b 48 31 30 31 35 35 7d 20 3c 53  ines {H10155} <S
c810: 32 30 31 32 30 3e 0a 2a 2a 20 45 58 50 45 52 49  20120>.** EXPERI
c820: 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20  MENTAL.**.** An 
c830: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
c840: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
c850: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
c860: 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
c870: 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
c880: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c890: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
c8a0: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
c8b0: 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
c8c0: 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
c8d0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
c8e0: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
c8f0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
c900: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
c910: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
c920: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
c930: 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
c940: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
c950: 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
c960: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20  ONFIG_MALLOC].  
c970: 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69  By creating an i
c980: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
c990: 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61  object.** and pa
c9a0: 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
c9b0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 64  ite3_config()] d
c9c0: 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  uring configurat
c9d0: 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 70 70 6c 69  ion, an.** appli
c9e0: 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
c9f0: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
ca00: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
ca10: 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a  ion subsystem.**
ca20: 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
ca30: 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
ca40: 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
ca50: 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   needs..**.** No
ca60: 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  te that SQLite c
ca70: 6f 6d 65 73 20 77 69 74 68 20 61 20 62 75 69 6c  omes with a buil
ca80: 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
ca90: 63 61 74 6f 72 20 74 68 61 74 20 69 73 0a 2a 2a  cator that is.**
caa0: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
cab0: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
cac0: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
cad0: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
cae0: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
caf0: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
cb00: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
cb10: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
cb20: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
cb30: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
cb40: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
cb50: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
cb60: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
cb70: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
cb80: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
cb90: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
cba0: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
cbb0: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
cbc0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
cbd0: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
cbe0: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
cbf0: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
cc00: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
cc10: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
cc20: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
cc30: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
cc40: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
cc50: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 46   The xMalloc, xF
cc60: 72 65 65 2c 20 61 6e 64 20 78 52 65 61 6c 6c 6f  ree, and xReallo
cc70: 63 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  c methods must w
cc80: 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
cc90: 6d 61 6c 6c 6f 63 28 29 2c 20 66 72 65 65 28 29  malloc(), free()
cca0: 2c 20 61 6e 64 20 72 65 61 6c 6c 6f 63 28 29 20  , and realloc() 
ccb0: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
ccc0: 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72  he standard libr
ccd0: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  ary..**.** xSize
cce0: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
ccf0: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
cd00: 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
cd10: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
cd20: 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
cd30: 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
cd40: 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
cd50: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
cd60: 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
cd70: 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
cd80: 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
cd90: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
cda0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
cdb0: 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
cdc0: 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
cdd0: 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
cde0: 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
cdf0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
ce00: 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
ce10: 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
ce20: 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
ce30: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
ce40: 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
ce50: 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
ce60: 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
ce70: 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
ce80: 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
ce90: 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
cea0: 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
ceb0: 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
cec0: 66 20 32 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  f 2..**.** The x
ced0: 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74  Init method init
cee0: 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f  ializes the memo
cef0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28  ry allocator.  (
cf00: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
cf10: 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
cf20: 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
cf30: 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
cf40: 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
cf50: 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
cf60: 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
cf70: 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
cf80: 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
cf90: 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
cfa0: 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
cfb0: 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
cfc0: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
cfd0: 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
cfe0: 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
cff0: 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
d000: 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
d010: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
d020: 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
d030: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
d040: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
d050: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
d060: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
d070: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
d080: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
d090: 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
d0a0: 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
d0b0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
d0c0: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
d0d0: 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
d0e0: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
d0f0: 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
d100: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
d110: 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
d120: 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
d130: 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
d140: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
d150: 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
d160: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
d170: 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
d180: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
d190: 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
d1a0: 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
d1b0: 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
d1c0: 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
d1d0: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
d1e0: 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
d1f0: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
d200: 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
d210: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
d220: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
d230: 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
d240: 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
d250: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
d260: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
d270: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
d280: 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
d290: 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
d2a0: 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
d2b0: 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
d2c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
d2d0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
d2e0: 69 6f 6e 73 20 7b 48 31 30 31 36 30 7d 20 3c 53  ions {H10160} <S
d2f0: 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  20000>.** EXPERI
d300: 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65  MENTAL.**.** The
d310: 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
d320: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
d330: 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
d340: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
d350: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
d360: 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
d370: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
d380: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
d390: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
d3a0: 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
d3b0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
d3c0: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
d3d0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
d3e0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
d3f0: 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
d400: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
d410: 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
d420: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
d430: 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
d440: 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
d450: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
d460: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
d470: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
d480: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
d490: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
d4a0: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
d4b0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
d4c0: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
d4d0: 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
d4e0: 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
d4f0: 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
d500: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
d510: 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
d520: 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
d530: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
d540: 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
d550: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
d560: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
d570: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69  his option.  Thi
d580: 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65  s option disable
d590: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
d5a0: 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
d5b0: 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
d5c0: 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
d5d0: 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
d5e0: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 3c 2f  single thread.</
d5f0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
d600: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
d610: 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
d620: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
d630: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
d640: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73  is option.  This
d650: 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73   option disables
d660: 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
d670: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
d680: 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
d690: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
d6a0: 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
d6b0: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
d6c0: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
d6d0: 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
d6e0: 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
d6f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
d700: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
d710: 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
d720: 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
d730: 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
d740: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
d750: 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
d760: 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
d770: 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
d780: 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
d790: 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
d7a0: 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
d7b0: 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
d7c0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
d7d0: 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 53  he same time.  S
d7e0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
d7f0: 67 20 6d 6f 64 65 5d 0a 2a 2a 20 64 6f 63 75 6d  g mode].** docum
d800: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
d810: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
d820: 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
d830: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
d840: 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74  G_SERIALIZED</dt
d850: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
d860: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
d870: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
d880: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   This option ena
d890: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
d8a0: 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
d8b0: 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
d8c0: 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
d8d0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
d8e0: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
d8f0: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
d900: 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
d910: 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
d920: 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
d930: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
d940: 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
d950: 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
d960: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
d970: 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
d980: 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
d990: 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
d9a0: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
d9b0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
d9c0: 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
d9d0: 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
d9e0: 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
d9f0: 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
da00: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
da10: 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
da20: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
da30: 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
da40: 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
da50: 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 53 65 65  ame time..** See
da60: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
da70: 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74  mode] documentat
da80: 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
da90: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c  al information.<
daa0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
dab0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
dac0: 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
dad0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
dae0: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
daf0: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
db00: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
db10: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
db20: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
db30: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
db40: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
db50: 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
db60: 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
db70: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
db80: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
db90: 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
dba0: 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
dbb0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
dbc0: 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
dbd0: 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a   SQLite.</dd>.**
dbe0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
dbf0: 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c  ONFIG_GETMALLOC<
dc00: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
dc10: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
dc20: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
dc30: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
dc40: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
dc50: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
dc60: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
dc70: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
dc80: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
dc90: 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
dca0: 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
dcb0: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
dcc0: 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
dcd0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
dce0: 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70  ines..** This op
dcf0: 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
dd00: 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
dd10: 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
dd20: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
dd30: 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
dd40: 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c  apper that simul
dd50: 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c  ations memory al
dd60: 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
dd70: 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65   or.** tracks me
dd80: 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20  mory usage, for 
dd90: 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a  example.</dd>.**
dda0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
ddb0: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
ddc0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
ddd0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
dde0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
ddf0: 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
de00: 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
de10: 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
de20: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
de30: 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
de40: 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
de50: 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
de60: 73 74 69 63 73 2e 20 57 68 65 6e 20 64 69 73 61  stics. When disa
de70: 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77  bled, the follow
de80: 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
de90: 66 61 63 65 73 20 62 65 63 6f 6d 65 20 0a 2a 2a  faces become .**
dea0: 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
deb0: 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
dec0: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
ded0: 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
dee0: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
def0: 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
df00: 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
df10: 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
df20: 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20  p_limit()].**   
df30: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
df40: 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  atus()].**   </u
df50: 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  l>.** </dd>.**.*
df60: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
df70: 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
df80: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
df90: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
dfa0: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
dfb0: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
dfc0: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
dfd0: 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
dfe0: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
dff0: 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70   arguments:  A p
e000: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
e010: 6d 6f 72 79 2c 20 74 68 65 0a 2a 2a 20 73 69 7a  mory, the.** siz
e020: 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63  e of each scratc
e030: 68 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61  h buffer (sz), a
e040: 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
e050: 20 62 75 66 66 65 72 73 20 28 4e 29 2e 20 20 54   buffers (N).  T
e060: 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e  he sz.** argumen
e070: 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74  t must be a mult
e080: 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68 65 20  iple of 16. The 
e090: 73 7a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f  sz parameter sho
e0a0: 75 6c 64 20 62 65 20 61 20 66 65 77 20 62 79 74  uld be a few byt
e0b0: 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74 68 61  es.** larger tha
e0c0: 6e 20 74 68 65 20 61 63 74 75 61 6c 20 73 63 72  n the actual scr
e0d0: 61 74 63 68 20 73 70 61 63 65 20 72 65 71 75 69  atch space requi
e0e0: 72 65 64 20 64 75 65 20 69 6e 74 65 72 6e 61 6c  red due internal
e0f0: 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68   overhead..** Th
e100: 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d  e first.** argum
e110: 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74  ent should point
e120: 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   to an allocatio
e130: 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  n of at least sz
e140: 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
e150: 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  ry..** SQLite wi
e160: 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74  ll use no more t
e170: 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20  han one scratch 
e180: 62 75 66 66 65 72 20 61 74 20 6f 6e 63 65 20 70  buffer at once p
e190: 65 72 20 74 68 72 65 61 64 2c 20 73 6f 0a 2a 2a  er thread, so.**
e1a0: 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74   N should be set
e1b0: 20 74 6f 20 74 68 65 20 65 78 70 65 63 74 65 64   to the expected
e1c0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
e1d0: 6f 66 20 74 68 72 65 61 64 73 2e 20 20 54 68 65  of threads.  The
e1e0: 20 73 7a 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72   sz.** parameter
e1f0: 20 73 68 6f 75 6c 64 20 62 65 20 36 20 74 69 6d   should be 6 tim
e200: 65 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  es the size of t
e210: 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
e220: 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a  ase page size..*
e230: 2a 20 53 63 72 61 74 63 68 20 62 75 66 66 65 72  * Scratch buffer
e240: 73 20 61 72 65 20 75 73 65 64 20 61 73 20 70 61  s are used as pa
e250: 72 74 20 6f 66 20 74 68 65 20 62 74 72 65 65 20  rt of the btree 
e260: 62 61 6c 61 6e 63 65 20 6f 70 65 72 61 74 69 6f  balance operatio
e270: 6e 2e 20 20 49 66 0a 2a 2a 20 54 68 65 20 62 74  n.  If.** The bt
e280: 72 65 65 20 62 61 6c 61 6e 63 65 72 20 6e 65 65  ree balancer nee
e290: 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 20 6d 65  ds additional me
e2a0: 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74  mory beyond what
e2b0: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 0a   is provided by.
e2c0: 2a 2a 20 73 63 72 61 74 63 68 20 62 75 66 66 65  ** scratch buffe
e2d0: 72 73 20 6f 72 20 69 66 20 6e 6f 20 73 63 72 61  rs or if no scra
e2e0: 74 63 68 20 62 75 66 66 65 72 20 73 70 61 63 65  tch buffer space
e2f0: 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
e300: 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6f  hen SQLite.** go
e310: 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
e320: 61 6c 6c 6f 63 28 29 5d 20 74 6f 20 6f 62 74 61  alloc()] to obta
e330: 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 74  in the memory it
e340: 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a   needs.</dd>.**.
e350: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
e360: 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
e370: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
e380: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
e390: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
e3a0: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
e3b0: 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
e3c0: 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
e3d0: 70 61 67 65 20 63 61 63 68 65 2e 20 20 54 68 65  page cache.  The
e3e0: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
e3f0: 75 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65  uments: A pointe
e400: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f  r to the.** memo
e410: 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ry, the size of 
e420: 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72  each page buffer
e430: 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
e440: 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28  umber of pages (
e450: 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
e460: 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
e470: 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
e480: 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
e490: 37 36 38 2e 20 20 54 68 65 20 66 69 72 73 74 0a  768.  The first.
e4a0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
e4b0: 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
e4c0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
e4d0: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
e4e0: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53   of memory..** S
e4f0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
e500: 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
e510: 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
e520: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69  argument to sati
e530: 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72  sfy its.** memor
e540: 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20  y needs for the 
e550: 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68  first N pages th
e560: 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61  at it adds to ca
e570: 63 68 65 2e 20 20 49 66 20 61 64 64 69 74 69 6f  che.  If additio
e580: 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
e590: 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
e5a0: 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
e5b0: 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
e5c0: 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a  is option, then.
e5d0: 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  ** SQLite goes t
e5e0: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
e5f0: 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64  c()] for the add
e600: 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20  itional storage 
e610: 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6d  space..** The im
e620: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
e630: 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f  ht use one or mo
e640: 72 65 20 6f 66 20 74 68 65 20 4e 20 62 75 66 66  re of the N buff
e650: 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20  ers to hold .** 
e660: 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e  memory accountin
e670: 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 3c  g information. <
e680: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
e690: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
e6a0: 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
e6b0: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
e6c0: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
e6d0: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
e6e0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
e6f0: 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ** for all of it
e700: 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
e710: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
e720: 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  s beyond those p
e730: 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62  rovided.** for b
e740: 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
e750: 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53  _SCRATCH] and [S
e760: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
e770: 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72  ECACHE]..** Ther
e780: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
e790: 6d 65 6e 74 73 3a 20 41 20 70 6f 69 6e 74 65 72  ments: A pointer
e7a0: 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20   to the memory, 
e7b0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
e7c0: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
e7d0: 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
e7e0: 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
e7f0: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 20 20 49  ocation size.  I
e800: 66 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  f.** the first p
e810: 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
e820: 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
e830: 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
e840: 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
e850: 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
e860: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
e870: 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
e880: 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
e890: 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
e8a0: 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
e8b0: 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
e8c0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
e8d0: 5d 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 6d 65  ].  If the.** me
e8e0: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
e8f0: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74  not NULL and eit
e900: 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  her [SQLITE_ENAB
e910: 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a  LE_MEMSYS3] or.*
e920: 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
e930: 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65  _MEMSYS5] are de
e940: 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20  fined, then the 
e950: 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
e960: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20  ry.** allocator 
e970: 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61  is engaged to ha
e980: 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69  ndle all of SQLi
e990: 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tes memory alloc
e9a0: 61 74 69 6f 6e 20 6e 65 65 64 73 2e 3c 2f 64 64  ation needs.</dd
e9b0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
e9c0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
e9d0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
e9e0: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
e9f0: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
ea00: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
ea10: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
ea20: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
ea30: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
ea40: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
ea50: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
ea60: 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
ea70: 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
ea80: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
ea90: 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
eaa0: 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20  ce.** the mutex 
eab0: 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
eac0: 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  nto SQLite.</dd>
ead0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
eae0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
eaf0: 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  X</dt>.** <dd>Th
eb00: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
eb10: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
eb20: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
eb30: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
eb40: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
eb50: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
eb60: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
eb70: 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
eb80: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
eb90: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
eba0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
ebb0: 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
ebc0: 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
ebd0: 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  s..** This optio
ebe0: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
ebf0: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
ec00: 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
ec10: 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
ec20: 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
ec30: 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
ec40: 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
ec50: 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
ec60: 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
ec70: 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
ec80: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
ec90: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
eca0: 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
ecb0: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
ecc0: 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
ecd0: 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
ece0: 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a  ine the default.
ecf0: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 63 61 74  ** memory allcat
ed00: 69 6f 6e 20 6c 6f 6f 6b 61 73 69 64 65 20 6f 70  ion lookaside op
ed10: 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 20 54 68 65  timization.  The
ed20: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
ed30: 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
ed40: 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
ed50: 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
ed60: 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
ed70: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
ed80: 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
ed90: 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
eda0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 3c 2f 64 64   connection.</dd
edb0: 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
edc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
edd0: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
ede0: 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
edf0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
ee00: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
ee10: 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
ee20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ee30: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
ee40: 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
ee50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
ee60: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
ee70: 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
ee80: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
ee90: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
eea0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
eeb0: 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
eec0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
eed0: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
eee0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
eef0: 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
ef00: 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
ef10: 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
ef20: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
ef30: 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
ef40: 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
ef50: 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
ef60: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
ef70: 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
ef80: 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
ef90: 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
efa0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
efb0: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
efc0: 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
efd0: 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
efe0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
eff0: 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
f000: 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
f010: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
f020: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
f030: 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
f040: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
f050: 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
f060: 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
f070: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
f080: 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
f090: 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
f0a0: 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
f0b0: 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
f0c0: 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
f0d0: 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
f0e0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
f0f0: 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
f100: 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
f110: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
f120: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
f130: 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
f140: 31 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  15  /* sqlite3_p
f150: 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a  cache_methods* *
f160: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
f170: 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
f180: 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 37 30   Options {H10170
f190: 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58  } <S20000>.** EX
f1a0: 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
f1b0: 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
f1c0: 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
f1d0: 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
f1e0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
f1f0: 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
f200: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
f210: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
f220: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
f230: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
f240: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
f250: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
f260: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
f270: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
f280: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
f290: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
f2a0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
f2b0: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
f2c0: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
f2d0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
f2e0: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
f2f0: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
f300: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
f310: 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
f320: 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
f330: 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
f340: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
f350: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
f360: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
f370: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
f380: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
f390: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
f3a0: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
f3b0: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
f3c0: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
f3d0: 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
f3e0: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
f3f0: 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
f400: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
f410: 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
f420: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
f430: 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
f440: 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
f450: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
f460: 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
f470: 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
f480: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
f490: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
f4a0: 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
f4b0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
f4c0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
f4d0: 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
f4e0: 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
f4f0: 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
f500: 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
f510: 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ry.  The first.*
f520: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62  * argument may b
f530: 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
f540: 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
f550: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 6c 6f   allocate the lo
f560: 6f 6b 61 73 69 64 65 0a 2a 2a 20 62 75 66 66 65  okaside.** buffe
f570: 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
f580: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
f590: 5d 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ].  The second a
f5a0: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
f5b0: 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
f5c0: 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
f5d0: 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 74 68 69  slot and the thi
f5e0: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
f5f0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
f600: 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
f610: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
f620: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
f630: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
f640: 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
f650: 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
f660: 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
f670: 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
f680: 75 6d 65 6e 74 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  uments.</dd>.**.
f690: 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
f6a0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
f6b0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
f6c0: 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20   1001  /* void* 
f6d0: 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a  int int */.../*.
f6e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
f6f0: 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
f700: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
f710: 6f 64 65 73 20 7b 48 31 32 32 30 30 7d 20 3c 53  odes {H12200} <S
f720: 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  10700>.**.** The
f730: 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
f740: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
f750: 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
f760: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
f770: 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
f780: 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
f790: 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 54  ure of SQLite. T
f7a0: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
f7b0: 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20  lt.** codes are 
f7c0: 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
f7d0: 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ult for historic
f7e0: 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
f7f0: 20 63 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e   considerations.
f800: 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
f810: 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 31  S:.**.** {H12201
f820: 7d 20 45 61 63 68 20 6e 65 77 20 5b 64 61 74 61  } Each new [data
f830: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
f840: 20 73 68 61 6c 6c 20 68 61 76 65 20 74 68 65 0a   shall have the.
f850: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74  **          [ext
f860: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
f870: 65 73 5d 20 66 65 61 74 75 72 65 20 64 69 73 61  es] feature disa
f880: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
f890: 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30 32 7d 20  .**.** {H12202} 
f8a0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  The [sqlite3_ext
f8b0: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
f8c0: 65 73 28 44 2c 46 29 5d 20 69 6e 74 65 72 66 61  es(D,F)] interfa
f8d0: 63 65 20 73 68 61 6c 6c 20 65 6e 61 62 6c 65 0a  ce shall enable.
f8e0: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 65 78 74  **          [ext
f8f0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
f900: 65 73 5d 20 66 6f 72 20 74 68 65 20 20 5b 64 61  es] for the  [da
f910: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f920: 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20 20  n] D.**         
f930: 20 69 66 20 74 68 65 20 46 20 70 61 72 61 6d 65   if the F parame
f940: 74 65 72 20 69 73 20 74 72 75 65 2c 20 6f 72 20  ter is true, or 
f950: 64 69 73 61 62 6c 65 20 74 68 65 6d 20 69 66 20  disable them if 
f960: 46 20 69 73 20 66 61 6c 73 65 2e 0a 2a 2f 0a 69  F is false..*/.i
f970: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
f980: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
f990: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
f9a0: 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
f9b0: 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
f9c0: 65 72 74 20 52 6f 77 69 64 20 7b 48 31 32 32 32  ert Rowid {H1222
f9d0: 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a  0} <S10700>.**.*
f9e0: 2a 20 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20  * Each entry in 
f9f0: 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
fa00: 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
fa10: 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
fa20: 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
fa30: 20 74 68 65 20 22 72 6f 77 69 64 22 2e 20 54 68   the "rowid". Th
fa40: 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
fa50: 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
fa60: 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
fa70: 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
fa80: 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
fa90: 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
faa0: 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
fab0: 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
fac0: 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
fad0: 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
fae0: 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
faf0: 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
fb00: 74 79 70 65 20 49 4e 54 45 47 45 52 20 50 52 49  type INTEGER PRI
fb10: 4d 41 52 59 20 4b 45 59 20 74 68 65 6e 20 74 68  MARY KEY then th
fb20: 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
fb30: 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
fb40: 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
fb50: 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
fb60: 72 65 74 75 72 6e 73 20 74 68 65 20 72 6f 77 69  returns the rowi
fb70: 64 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65  d of the most re
fb80: 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66  cent.** successf
fb90: 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
fba0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
fbb0: 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  om the [database
fbc0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
fbd0: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
fbe0: 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73 75  ument.  If no su
fbf0: 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
fc00: 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20  ]s.** have ever 
fc10: 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74  occurred on that
fc20: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
fc30: 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65  tion, zero is re
fc40: 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  turned..**.** If
fc50: 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
fc60: 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
fc70: 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72  gger, then the r
fc80: 6f 77 69 64 20 6f 66 20 74 68 65 20 69 6e 73 65  owid of the inse
fc90: 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72  rted.** row is r
fca0: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
fcb0: 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20  routine as long 
fcc0: 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69  as the trigger i
fcd0: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75  s running..** Bu
fce0: 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67  t once the trigg
fcf0: 65 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74  er terminates, t
fd00: 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
fd10: 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  d by this routin
fd20: 65 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20  e.** reverts to 
fd30: 74 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69  the last value i
fd40: 6e 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 74  nserted before t
fd50: 68 65 20 74 72 69 67 67 65 72 20 66 69 72 65 64  he trigger fired
fd60: 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 49 4e 53 45  ..**.** An [INSE
fd70: 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64  RT] that fails d
fd80: 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69  ue to a constrai
fd90: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20  nt violation is 
fda0: 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73  not a.** success
fdb0: 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64  ful [INSERT] and
fdc0: 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
fdd0: 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
fde0: 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72  ned by this.** r
fdf0: 6f 75 74 69 6e 65 2e 20 20 54 68 75 73 20 49 4e  outine.  Thus IN
fe00: 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
fe10: 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
fe20: 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
fe30: 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
fe40: 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
fe50: 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
fe60: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
fe70: 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
fe80: 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
fe90: 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 57  ertion fails.  W
fea0: 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
feb0: 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
fec0: 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
fed0: 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
fee0: 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
fef0: 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
ff00: 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
ff10: 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
ff20: 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
ff30: 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
ff40: 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
ff50: 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
ff60: 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
ff70: 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
ff80: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
ff90: 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
ffa0: 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70 75 72 70  .** For the purp
ffb0: 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
ffc0: 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54  tine, an [INSERT
ffd0: 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  ] is considered 
ffe0: 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
fff0: 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
10000 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
10010 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
10020 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
10030 0a 2a 2a 20 7b 48 31 32 32 32 31 7d 20 54 68 65  .** {H12221} The
10040 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
10050 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 66  nsert_rowid()] f
10060 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65  unction shall re
10070 74 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a  turn the rowid.*
10080 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
10090 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  e most recent su
100a0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
100b0 5d 20 70 65 72 66 6f 72 6d 65 64 20 6f 6e 20 74  ] performed on t
100c0 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20  he same.**      
100d0 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f      [database co
100e0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 77 69  nnection] and wi
100f0 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  thin the same or
10100 20 68 69 67 68 65 72 20 6c 65 76 65 6c 0a 2a 2a   higher level.**
10110 20 20 20 20 20 20 20 20 20 20 74 72 69 67 67 65            trigge
10120 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a 65  r context, or ze
10130 72 6f 20 69 66 20 74 68 65 72 65 20 68 61 76 65  ro if there have
10140 20 62 65 65 6e 20 6e 6f 20 71 75 61 6c 69 66 79   been no qualify
10150 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
10160 5b 49 4e 53 45 52 54 5d 20 73 74 61 74 65 6d 65  [INSERT] stateme
10170 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  nts..**.** {H122
10180 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  23} The [sqlite3
10190 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
101a0 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73  id()] function s
101b0 68 61 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 0a  hall return the.
101c0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 61 6d 65  **          same
101d0 20 76 61 6c 75 65 20 77 68 65 6e 20 63 61 6c 6c   value when call
101e0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
101f0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
10200 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d 6d  .**          imm
10210 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20  ediately before 
10220 61 6e 64 20 61 66 74 65 72 20 61 20 5b 52 4f 4c  and after a [ROL
10230 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53  LBACK]..**.** AS
10240 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
10250 20 7b 41 31 32 32 33 32 7d 20 49 66 20 61 20 73   {A12232} If a s
10260 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
10270 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
10280 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
10290 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  me.**          d
102a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
102b0 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71  on while the [sq
102c0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
102d0 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 20 20  t_rowid()].**   
102e0 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 20         function 
102f0 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
10300 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
10310 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69  last insert rowi
10320 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  d,.**          t
10330 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
10340 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
10350 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
10360 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 20 20  owid()] is.**   
10370 20 20 20 20 20 20 20 75 6e 70 72 65 64 69 63 74         unpredict
10380 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
10390 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
103a0 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
103b0 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6c  ew.**          l
103c0 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64  ast insert rowid
103d0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
103e0 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
103f0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
10400 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
10410 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
10420 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
10430 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32  s Modified {H122
10440 34 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a  40} <S10600>.**.
10450 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
10460 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
10470 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
10480 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63  rows that were c
10490 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73  hanged.** or ins
104a0 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
104b0 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
104c0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
104d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
104e0 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
104f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
10500 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
10510 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
10520 2a 2a 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  ** Only changes 
10530 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c  that are directl
10540 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  y specified by t
10550 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50  he [INSERT], [UP
10560 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45  DATE],.** or [DE
10570 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20  LETE] statement 
10580 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75  are counted.  Au
10590 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
105a0 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69  caused by.** tri
105b0 67 67 65 72 73 20 61 72 65 20 6e 6f 74 20 63 6f  ggers are not co
105c0 75 6e 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b  unted. Use the [
105d0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
105e0 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
105f0 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64 20 74 68 65  n.** to find the
10600 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
10610 20 63 68 61 6e 67 65 73 20 69 6e 63 6c 75 64 69   changes includi
10620 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ng changes cause
10630 64 20 62 79 20 74 72 69 67 67 65 72 73 2e 0a 2a  d by triggers..*
10640 2a 0a 2a 2a 20 41 20 22 72 6f 77 20 63 68 61 6e  *.** A "row chan
10650 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20  ge" is a change 
10660 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  to a single row 
10670 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c  of a single tabl
10680 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61  e.** caused by a
10690 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45  n INSERT, DELETE
106a0 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74  , or UPDATE stat
106b0 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61  ement.  Rows tha
106c0 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64  t.** are changed
106d0 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73   as side effects
106e0 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73   of REPLACE cons
106f0 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
10700 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
10710 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
10720 2c 20 44 52 4f 50 20 54 41 42 4c 45 2c 20 6f 72  , DROP TABLE, or
10730 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
10740 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
10750 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
10760 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 0a  ct row changes..
10770 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72  **.** A "trigger
10780 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73   context" is a s
10790 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f  cope of executio
107a0 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e  n that begins an
107b0 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74  d.** ends with t
107c0 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 74  he script of a t
107d0 72 69 67 67 65 72 2e 20 20 4d 6f 73 74 20 53 51  rigger.  Most SQ
107e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
107f0 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75  .** evaluated ou
10800 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69  tside of any tri
10810 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74  gger.  This is t
10820 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a  he "top level".*
10830 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
10840 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72  t.  If a trigger
10850 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20   fires from the 
10860 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20  top level, a.** 
10870 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
10880 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66  ext is entered f
10890 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20  or the duration 
108a0 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74  of that one.** t
108b0 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67  rigger.  Subtrig
108c0 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63  gers create subc
108d0 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69  ontexts for thei
108e0 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  r duration..**.*
108f0 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * Calling [sqlit
10900 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73  e3_exec()] or [s
10910 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
10920 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a  ecursively does.
10930 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20  ** not create a 
10940 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
10950 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ext..**.** This 
10960 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
10970 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
10980 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
10990 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74  s in the.** most
109a0 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
109b0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
109c0 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
109d0 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74  in the same.** t
109e0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
109f0 2a 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e  **.** Thus, when
10a00 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
10a10 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73   top level, this
10a20 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
10a30 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
10a40 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  of changes in th
10a50 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
10a60 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
10a70 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
10a80 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74  also occurred at
10a90 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20   the top level. 
10aa0 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   Within the body
10ab0 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a   of a trigger,.*
10ac0 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  * the sqlite3_ch
10ad0 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63  anges() interfac
10ae0 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
10af0 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
10b00 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73  er of.** changes
10b10 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
10b20 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
10b30 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
10b40 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
10b50 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
10b60 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61  e body of the sa
10b70 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48  me trigger..** H
10b80 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62  owever, the numb
10b90 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  er returned does
10ba0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
10bb0 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62  nges.** caused b
10bc0 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69  y subtriggers si
10bd0 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74  nce those have t
10be0 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74  heir own context
10bf0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
10c00 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 63 6f  mplements the co
10c10 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20 46 52  mmand "DELETE FR
10c20 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68 6f 75  OM table" withou
10c30 74 20 61 20 57 48 45 52 45 20 63 6c 61 75 73 65  t a WHERE clause
10c40 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e 67 20  .** by dropping 
10c50 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67 20 74  and recreating t
10c60 68 65 20 74 61 62 6c 65 2e 20 20 44 6f 69 6e 67  he table.  Doing
10c70 20 73 6f 20 69 73 20 6d 75 63 68 20 66 61 73 74   so is much fast
10c80 65 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a  er than going.**
10c90 20 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c   through and del
10ca0 65 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c  eting individual
10cb0 20 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74   elements from t
10cc0 68 65 20 74 61 62 6c 65 2e 20 20 42 65 63 61 75  he table.  Becau
10cd0 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70  se of this.** op
10ce0 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20  timization, the 
10cf0 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22 44 45  deletions in "DE
10d00 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22  LETE FROM table"
10d10 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63 68 61   are not row cha
10d20 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c  nges and.** will
10d30 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20   not be counted 
10d40 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  by the sqlite3_c
10d50 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73 71 6c  hanges() or [sql
10d60 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
10d70 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  es()].** functio
10d80 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ns, regardless o
10d90 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
10da0 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65  elements that we
10db0 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  re originally.**
10dc0 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 20   in the table.  
10dd0 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61  To get an accura
10de0 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20  te count of the 
10df0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64  number of rows d
10e00 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22  eleted, use.** "
10e10 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
10e20 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65  e WHERE 1" inste
10e30 61 64 2e 20 20 4f 72 20 72 65 63 6f 6d 70 69 6c  ad.  Or recompil
10e40 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
10e50 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 55 4e  SQLITE_OMIT_TRUN
10e60 43 41 54 45 5f 4f 50 54 49 4d 49 5a 41 54 49 4f  CATE_OPTIMIZATIO
10e70 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
10e80 6f 70 74 69 6f 6e 20 74 6f 20 64 69 73 61 62 6c  option to disabl
10e90 65 20 74 68 65 0a 2a 2a 20 6f 70 74 69 6d 69 7a  e the.** optimiz
10ea0 61 74 69 6f 6e 20 6f 6e 20 61 6c 6c 20 71 75 65  ation on all que
10eb0 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ries..**.** INVA
10ec0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
10ed0 31 32 32 34 31 7d 20 54 68 65 20 5b 73 71 6c 69  12241} The [sqli
10ee0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  te3_changes()] f
10ef0 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65  unction shall re
10f00 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
10f10 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  of.**          r
10f20 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ow changes cause
10f30 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
10f40 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
10f50 41 54 45 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ATE,.**         
10f60 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
10f70 6d 65 6e 74 20 6f 6e 20 74 68 65 20 73 61 6d 65  ment on the same
10f80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
10f90 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20  tion and.**     
10fa0 20 20 20 20 20 77 69 74 68 69 6e 20 74 68 65 20       within the 
10fb0 73 61 6d 65 20 6f 72 20 68 69 67 68 65 72 20 74  same or higher t
10fc0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2c 20  rigger context, 
10fd0 6f 72 20 7a 65 72 6f 20 69 66 20 74 68 65 72 65  or zero if there
10fe0 20 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20   have.**        
10ff0 20 20 6e 6f 74 20 62 65 65 6e 20 61 6e 79 20 71    not been any q
11000 75 61 6c 69 66 79 69 6e 67 20 72 6f 77 20 63 68  ualifying row ch
11010 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  anges..**.** {H1
11020 32 32 34 33 7d 20 53 74 61 74 65 6d 65 6e 74 73  2243} Statements
11030 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44 45   of the form "DE
11040 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 6e  LETE FROM tablen
11050 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a 20  ame" with no.** 
11060 20 20 20 20 20 20 20 20 20 57 48 45 52 45 20 63           WHERE c
11070 6c 61 75 73 65 20 73 68 61 6c 6c 20 63 61 75 73  lause shall caus
11080 65 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  e subsequent cal
11090 6c 73 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20  ls to.**        
110a0 20 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67    [sqlite3_chang
110b0 65 73 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 20  es()] to return 
110c0 7a 65 72 6f 2c 20 72 65 67 61 72 64 6c 65 73 73  zero, regardless
110d0 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
110e0 20 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f      number of ro
110f0 77 73 20 6f 72 69 67 69 6e 61 6c 6c 79 20 69 6e  ws originally in
11100 20 74 68 65 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a   the table..**.*
11110 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a  * ASSUMPTIONS:.*
11120 2a 0a 2a 2a 20 7b 41 31 32 32 35 32 7d 20 49 66  *.** {A12252} If
11130 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
11140 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
11150 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
11160 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11170 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 69  .**          whi
11180 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  le [sqlite3_chan
11190 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
111a0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
111b0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20 20   returned.**    
111c0 20 20 20 20 20 20 69 73 20 75 6e 70 72 65 64 69        is unpredi
111d0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
111e0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
111f0 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
11200 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
11210 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
11220 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
11230 77 73 20 4d 6f 64 69 66 69 65 64 20 7b 48 31 32  ws Modified {H12
11240 32 36 30 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a  260} <S10600>.**
11250 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
11260 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
11270 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
11280 67 65 73 20 63 61 75 73 65 64 20 62 79 20 49 4e  ges caused by IN
11290 53 45 52 54 2c 0a 2a 2a 20 55 50 44 41 54 45 20  SERT,.** UPDATE 
112a0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
112b0 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b  ents since the [
112c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
112d0 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e  ion] was opened.
112e0 0a 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20 69 6e  .** The count in
112f0 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67  cludes all chang
11300 65 73 20 66 72 6f 6d 20 61 6c 6c 20 74 72 69 67  es from all trig
11310 67 65 72 20 63 6f 6e 74 65 78 74 73 2e 20 20 48  ger contexts.  H
11320 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63  owever,.** the c
11330 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
11340 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73  clude changes us
11350 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
11360 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69  REPLACE constrai
11370 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62  nts,.** do rollb
11380 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72  acks or ABORT pr
11390 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 44 52 4f  ocessing, or DRO
113a0 50 20 74 61 62 6c 65 20 70 72 6f 63 65 73 73 69  P table processi
113b0 6e 67 2e 0a 2a 2a 20 54 68 65 20 63 68 61 6e 67  ng..** The chang
113c0 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 20 61  es are counted a
113d0 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 73 74  s soon as the st
113e0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b  atement that mak
113f0 65 73 20 74 68 65 6d 20 69 73 0a 2a 2a 20 63 6f  es them is.** co
11400 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
11410 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
11420 6c 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 20  le is passed to 
11430 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
11440 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
11450 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
11460 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6d 70 6c  *.** SQLite impl
11470 65 6d 65 6e 74 73 20 74 68 65 20 63 6f 6d 6d 61  ements the comma
11480 6e 64 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  nd "DELETE FROM 
11490 74 61 62 6c 65 22 20 77 69 74 68 6f 75 74 20 61  table" without a
114a0 20 57 48 45 52 45 20 63 6c 61 75 73 65 0a 2a 2a   WHERE clause.**
114b0 20 62 79 20 64 72 6f 70 70 69 6e 67 20 61 6e 64   by dropping and
114c0 20 72 65 63 72 65 61 74 69 6e 67 20 74 68 65 20   recreating the 
114d0 74 61 62 6c 65 2e 20 20 28 54 68 69 73 20 69 73  table.  (This is
114e0 20 6d 75 63 68 20 66 61 73 74 65 72 20 74 68 61   much faster tha
114f0 6e 20 67 6f 69 6e 67 0a 2a 2a 20 74 68 72 6f 75  n going.** throu
11500 67 68 20 61 6e 64 20 64 65 6c 65 74 69 6e 67 20  gh and deleting 
11510 69 6e 64 69 76 69 64 75 61 6c 20 65 6c 65 6d 65  individual eleme
11520 6e 74 73 20 66 72 6f 6d 20 74 68 65 20 74 61 62  nts from the tab
11530 6c 65 2e 29 20 20 42 65 63 61 75 73 65 20 6f 66  le.)  Because of
11540 20 74 68 69 73 0a 2a 2a 20 6f 70 74 69 6d 69 7a   this.** optimiz
11550 61 74 69 6f 6e 2c 20 74 68 65 20 64 65 6c 65 74  ation, the delet
11560 69 6f 6e 73 20 69 6e 20 22 44 45 4c 45 54 45 20  ions in "DELETE 
11570 46 52 4f 4d 20 74 61 62 6c 65 22 20 61 72 65 20  FROM table" are 
11580 6e 6f 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  not row changes 
11590 61 6e 64 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  and.** will not 
115a0 62 65 20 63 6f 75 6e 74 65 64 20 62 79 20 74 68  be counted by th
115b0 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
115c0 73 28 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  s() or [sqlite3_
115d0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
115e0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2c 20 72  .** functions, r
115f0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
11600 20 6e 75 6d 62 65 72 20 6f 66 20 65 6c 65 6d 65   number of eleme
11610 6e 74 73 20 74 68 61 74 20 77 65 72 65 20 6f 72  nts that were or
11620 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 69 6e 20 74  iginally.** in t
11630 68 65 20 74 61 62 6c 65 2e 20 20 54 6f 20 67 65  he table.  To ge
11640 74 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f  t an accurate co
11650 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  unt of the numbe
11660 72 20 6f 66 20 72 6f 77 73 20 64 65 6c 65 74 65  r of rows delete
11670 64 2c 20 75 73 65 0a 2a 2a 20 22 44 45 4c 45 54  d, use.** "DELET
11680 45 20 46 52 4f 4d 20 74 61 62 6c 65 20 57 48 45  E FROM table WHE
11690 52 45 20 31 22 20 69 6e 73 74 65 61 64 2e 20 20  RE 1" instead.  
116a0 20 4f 72 20 72 65 63 6f 6d 70 69 6c 65 20 75 73   Or recompile us
116b0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
116c0 54 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 41 54 45  TE_OMIT_TRUNCATE
116d0 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 5d 20 63  _OPTIMIZATION] c
116e0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
116f0 6f 6e 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68  on to disable th
11700 65 0a 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f  e.** optimizatio
11710 6e 20 6f 6e 20 61 6c 6c 20 71 75 65 72 69 65 73  n on all queries
11720 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
11730 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
11740 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
11750 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ce..**.** INVARI
11760 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
11770 32 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  261} The [sqlite
11780 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
11790 29 5d 20 72 65 74 75 72 6e 73 20 74 68 65 20 74  )] returns the t
117a0 6f 74 61 6c 20 6e 75 6d 62 65 72 0a 2a 2a 20 20  otal number.**  
117b0 20 20 20 20 20 20 20 20 6f 66 20 72 6f 77 20 63          of row c
117c0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
117d0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
117e0 20 61 6e 64 2f 6f 72 20 44 45 4c 45 54 45 0a 2a   and/or DELETE.*
117f0 2a 20 20 20 20 20 20 20 20 20 20 73 74 61 74 65  *          state
11800 6d 65 6e 74 73 20 6f 6e 20 74 68 65 20 73 61 6d  ments on the sam
11810 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
11820 65 63 74 69 6f 6e 5d 2c 20 69 6e 20 61 6e 79 0a  ection], in any.
11830 2a 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 67  **          trig
11840 67 65 72 20 63 6f 6e 74 65 78 74 2c 20 73 69 6e  ger context, sin
11850 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ce the database 
11860 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 63  connection was c
11870 72 65 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48  reated..**.** {H
11880 31 32 32 36 33 7d 20 53 74 61 74 65 6d 65 6e 74  12263} Statement
11890 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 44  s of the form "D
118a0 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65  ELETE FROM table
118b0 6e 61 6d 65 22 20 77 69 74 68 20 6e 6f 0a 2a 2a  name" with no.**
118c0 20 20 20 20 20 20 20 20 20 20 57 48 45 52 45 20            WHERE 
118d0 63 6c 61 75 73 65 20 73 68 61 6c 6c 20 6e 6f 74  clause shall not
118e0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
118f0 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 20 20  e returned.**   
11900 20 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74         by [sqlit
11910 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
11920 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d  ()]..**.** ASSUM
11930 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41  PTIONS:.**.** {A
11940 31 32 32 36 34 7d 20 49 66 20 61 20 73 65 70 61  12264} If a sepa
11950 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
11960 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
11970 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
11980 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20 20  onnection.**    
11990 20 20 20 20 20 20 77 68 69 6c 65 20 5b 73 71 6c        while [sql
119a0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
119b0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
119c0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
119d0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
119e0 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63  rned is unpredic
119f0 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
11a00 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
11a10 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
11a20 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
11a30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11a40 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
11a50 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
11a60 79 20 7b 48 31 32 32 37 30 7d 20 3c 53 33 30 35  y {H12270} <S305
11a70 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  00>.**.** This f
11a80 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
11a90 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
11aa0 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
11ab0 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
11ac0 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
11ad0 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
11ae0 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
11af0 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
11b00 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
11b10 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
11b20 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
11b30 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
11b40 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
11b50 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
11b60 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
11b70 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
11b80 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
11b90 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 74  .** It is safe t
11ba0 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
11bb0 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
11bc0 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
11bd0 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
11be0 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
11bf0 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
11c00 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
11c10 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
11c20 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
11c30 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
11c40 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
11c50 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a  nnection] that.*
11c60 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d  * is closed or m
11c70 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72  ight close befor
11c80 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
11c90 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a  upt() returns..*
11ca0 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f  *.** If an SQL o
11cb0 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
11cc0 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
11cd0 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
11ce0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
11cf0 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
11d00 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
11d10 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
11d20 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
11d30 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
11d40 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
11d50 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
11d60 0a 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70  .**.** An SQL op
11d70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
11d80 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
11d90 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
11da0 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49  INTERRUPT]..** I
11db0 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
11dc0 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
11dd0 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
11de0 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
11df0 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
11e00 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
11e10 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
11e20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
11e30 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
11e40 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
11e50 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
11e60 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
11e70 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
11e80 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
11e90 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
11ea0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
11eb0 72 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  rted after sqlit
11ec0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
11ed0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e  eturns..**.** IN
11ee0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
11ef0 7b 48 31 32 32 37 31 7d 20 54 68 65 20 5b 73 71  {H12271} The [sq
11f00 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
11f10 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
11f20 6c 20 66 6f 72 63 65 20 61 6c 6c 20 72 75 6e 6e  l force all runn
11f30 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
11f40 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
11f50 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
11f60 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
11f70 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20   connection.**  
11f80 20 20 20 20 20 20 20 20 74 6f 20 68 61 6c 74 20          to halt 
11f90 61 66 74 65 72 20 70 72 6f 63 65 73 73 69 6e 67  after processing
11fa0 20 61 74 20 6d 6f 73 74 20 6f 6e 65 20 61 64 64   at most one add
11fb0 69 74 69 6f 6e 61 6c 20 72 6f 77 20 6f 66 20 64  itional row of d
11fc0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32  ata..**.** {H122
11fd0 37 32 7d 20 41 6e 79 20 53 51 4c 20 73 74 61 74  72} Any SQL stat
11fe0 65 6d 65 6e 74 20 74 68 61 74 20 69 73 20 69 6e  ement that is in
11ff0 74 65 72 72 75 70 74 65 64 20 62 79 20 5b 73 71  terrupted by [sq
12000 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
12010 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  )].**          w
12020 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
12030 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
12040 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53  *.** ASSUMPTIONS
12050 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 37 39 7d  :.**.** {A12279}
12060 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
12070 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
12080 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
12090 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
120a0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 72 75  *          is ru
120b0 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74  nning then bad t
120c0 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c  hings will likel
120d0 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69  y happen..*/.voi
120e0 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
120f0 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
12100 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12110 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
12120 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
12130 20 43 6f 6d 70 6c 65 74 65 20 7b 48 31 30 35 31   Complete {H1051
12140 30 7d 20 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a  0} <S70200>.**.*
12150 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
12160 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
12170 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70  command-line inp
12180 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ut to determine 
12190 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  if the.** curren
121a0 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74  tly entered text
121b0 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 63   seems to form c
121c0 6f 6d 70 6c 65 74 65 20 61 20 53 51 4c 20 73 74  omplete a SQL st
121d0 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66  atement or.** if
121e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75   additional inpu
121f0 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f  t is needed befo
12200 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74  re sending the t
12210 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  ext into.** SQLi
12220 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
12230 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
12240 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74  return true if t
12250 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
12260 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
12270 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
12280 73 74 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74  statement.  A st
12290 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65  atement is judge
122a0 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c  d to be.** compl
122b0 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77  ete if it ends w
122c0 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
122d0 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74  token and is not
122e0 20 61 20 66 72 61 67 6d 65 6e 74 20 6f 66 20 61   a fragment of a
122f0 0a 2a 2a 20 43 52 45 41 54 45 20 54 52 49 47 47  .** CREATE TRIGG
12300 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 53  ER statement.  S
12310 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
12320 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
12330 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
12340 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
12350 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
12360 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
12370 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
12380 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
12390 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
123a0 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
123b0 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
123c0 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
123d0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
123e0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
123f0 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  nator..**.** The
12400 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
12410 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
12420 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
12430 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
12440 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
12450 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
12460 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
12470 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 31  S:.**.** {H10511
12480 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 65  } A successful e
12490 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71  valuation of [sq
124a0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
124b0 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  ] or.**         
124c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
124d0 74 65 31 36 28 29 5d 20 66 75 6e 63 74 69 6f 6e  te16()] function
124e0 73 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  s shall.**      
124f0 20 20 20 20 72 65 74 75 72 6e 20 61 20 6e 75 6d      return a num
12500 65 72 69 63 20 31 20 69 66 20 61 6e 64 20 6f 6e  eric 1 if and on
12510 6c 79 20 69 66 20 74 68 65 20 6c 61 73 74 20 6e  ly if the last n
12520 6f 6e 2d 77 68 69 74 65 73 70 61 63 65 0a 2a 2a  on-whitespace.**
12530 20 20 20 20 20 20 20 20 20 20 74 6f 6b 65 6e 20            token 
12540 69 6e 20 74 68 65 69 72 20 69 6e 70 75 74 20 69  in their input i
12550 73 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 68  s a semicolon th
12560 61 74 20 69 73 20 6e 6f 74 20 69 6e 20 62 65 74  at is not in bet
12570 77 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ween.**         
12580 20 74 68 65 20 42 45 47 49 4e 20 61 6e 64 20 45   the BEGIN and E
12590 4e 44 20 6f 66 20 61 20 43 52 45 41 54 45 20 54  ND of a CREATE T
125a0 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
125b0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35 31 32 7d  ..**.** {H10512}
125c0 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   If a memory all
125d0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
125e0 63 75 72 73 20 64 75 72 69 6e 67 20 61 6e 20 69  curs during an i
125f0 6e 76 6f 63 61 74 69 6f 6e 0a 2a 2a 20 20 20 20  nvocation.**    
12600 20 20 20 20 20 20 6f 66 20 5b 73 71 6c 69 74 65        of [sqlite
12610 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6f 72  3_complete()] or
12620 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
12630 74 65 31 36 28 29 5d 20 74 68 65 6e 20 74 68 65  te16()] then the
12640 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 6f 75  .**          rou
12650 74 69 6e 65 20 73 68 61 6c 6c 20 72 65 74 75 72  tine shall retur
12660 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
12670 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49  ..**.** ASSUMPTI
12680 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 30 35  ONS:.**.** {A105
12690 31 32 7d 20 54 68 65 20 69 6e 70 75 74 20 74 6f  12} The input to
126a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
126b0 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
126c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
126d0 2a 2a 20 20 20 20 20 20 20 20 20 20 55 54 46 2d  **          UTF-
126e0 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
126f0 7b 41 31 30 35 31 33 7d 20 54 68 65 20 69 6e 70  {A10513} The inp
12700 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
12710 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73  omplete16()] mus
12720 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
12730 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20  inated.**       
12740 20 20 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67     UTF-16 string
12750 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
12760 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  order..*/.int sq
12770 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63  lite3_complete(c
12780 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b  onst char *sql);
12790 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
127a0 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
127b0 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
127c0 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
127d0 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
127e0 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
127f0 42 55 53 59 20 45 72 72 6f 72 73 20 7b 48 31 32  BUSY Errors {H12
12800 33 31 30 7d 20 3c 53 34 30 34 30 30 3e 0a 2a 2a  310} <S40400>.**
12810 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
12820 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b   sets a callback
12830 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d   function that m
12840 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
12850 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
12860 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
12870 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73  o open a databas
12880 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f  e table that ano
12890 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f  ther thread.** o
128a0 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f  r process has lo
128b0 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  cked..**.** If t
128c0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
128d0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
128e0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
128f0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
12900 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74  OCKED].** is ret
12910 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
12920 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
12930 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 49 66  ing the lock. If
12940 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
12950 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ck.** is not NUL
12960 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  L, then the call
12970 62 61 63 6b 20 77 69 6c 6c 20 62 65 20 69 6e 76  back will be inv
12980 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72  oked with two ar
12990 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  guments..**.** T
129a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
129b0 74 20 74 6f 20 74 68 65 20 68 61 6e 64 6c 65 72  t to the handler
129c0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
129d0 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
129e0 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
129f0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
12a00 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
12a10 61 6e 64 6c 65 72 28 29 2e 20 20 54 68 65 20 73  andler().  The s
12a20 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
12a30 6f 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  o.** the handler
12a40 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
12a50 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
12a60 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
12a70 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
12a80 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74  en invoked for t
12a90 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  his locking even
12aa0 74 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 62 75  t.  If the.** bu
12ab0 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
12ac0 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
12ad0 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
12ae0 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
12af0 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
12b00 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
12b10 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
12b20 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
12b30 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
12b40 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63  * If the callbac
12b50 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
12b60 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
12b70 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
12b80 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ade to open the 
12b90 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61  database for rea
12ba0 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63  ding and the cyc
12bb0 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
12bc0 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
12bd0 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
12be0 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
12bf0 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  tee that it will
12c00 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
12c10 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
12c20 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 49 66  k contention. If
12c30 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e   SQLite determin
12c40 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67  es that invoking
12c50 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e   the busy.** han
12c60 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c  dler could resul
12c70 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c  t in a deadlock,
12c80 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61   it will go ahea
12c90 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  d and return [SQ
12ca0 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72  LITE_BUSY].** or
12cb0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
12cc0 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20  LOCKED] instead 
12cd0 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
12ce0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
12cf0 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
12d00 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
12d10 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
12d20 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
12d30 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
12d40 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
12d50 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
12d60 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
12d70 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
12d80 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
12d90 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
12da0 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
12db0 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
12dc0 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
12dd0 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
12de0 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
12df0 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
12e00 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
12e10 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
12e20 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
12e30 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
12e40 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
12e50 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
12e60 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
12e70 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
12e80 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
12e90 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
12ea0 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
12eb0 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
12ec0 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
12ed0 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
12ee0 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
12ef0 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
12f00 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
12f10 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
12f20 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
12f30 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
12f40 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
12f50 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
12f60 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
12f70 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
12f80 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
12f90 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  L..**.** The [SQ
12fa0 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72  LITE_BUSY] error
12fb0 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   is converted to
12fc0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
12fd0 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20  LOCKED].** when 
12fe0 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65  SQLite is in the
12ff0 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72   middle of a lar
13000 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77  ge transaction w
13010 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20  here all the.** 
13020 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74  changes will not
13030 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e   fit into the in
13040 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20  -memory cache.  
13050 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61  SQLite will.** a
13060 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45  lready hold a RE
13070 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74  SERVED lock on t
13080 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
13090 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a  , but it needs.*
130a0 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69  * to promote thi
130b0 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53  s lock to EXCLUS
130c0 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63  IVE so that it c
130d0 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a  an spill cache.*
130e0 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65  * pages into the
130f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
13100 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63  ithout harm to c
13110 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61  oncurrent.** rea
13120 64 65 72 73 2e 20 20 49 66 20 69 74 20 69 73 20  ders.  If it is 
13130 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74  unable to promot
13140 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e  e the lock, then
13150 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a   the in-memory.*
13160 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20  * cache will be 
13170 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e  left in an incon
13180 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e  sistent state an
13190 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a  d so the error.*
131a0 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74  * code is promot
131b0 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61  ed from the rela
131c0 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53  tively benign [S
131d0 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a  QLITE_BUSY] to.*
131e0 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72  * the more sever
131f0 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  e [SQLITE_IOERR_
13200 42 4c 4f 43 4b 45 44 5d 2e 20 20 54 68 69 73 20  BLOCKED].  This 
13210 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
13220 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
13230 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
13240 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
13250 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ges.  See the.**
13260 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72   <a href="/cvstr
13270 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
13280 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
13290 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
132a0 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
132b0 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
132c0 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
132d0 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
132e0 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
132f0 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ant..**.** There
13300 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
13310 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
13320 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
13330 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
13340 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
13350 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
13360 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
13370 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
13380 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 20  ly set handler. 
13390 20 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69   Note that calli
133a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
133b0 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77  _timeout()].** w
133c0 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20  ill also set or 
133d0 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68  clear the busy h
133e0 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
133f0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
13400 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
13410 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
13420 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
13430 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13440 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
13450 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
13460 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  r.  Any such act
13470 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
13480 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
13490 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 49 4e 56  vior..** .** INV
134a0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
134b0 48 31 32 33 31 31 7d 20 54 68 65 20 5b 73 71 6c  H12311} The [sql
134c0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
134d0 72 28 44 2c 43 2c 41 29 5d 20 66 75 6e 63 74 69  r(D,C,A)] functi
134e0 6f 6e 20 73 68 61 6c 6c 20 72 65 70 6c 61 63 65  on shall replace
134f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75 73  .**          bus
13500 79 20 63 61 6c 6c 62 61 63 6b 20 69 6e 20 74 68  y callback in th
13510 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
13520 65 63 74 69 6f 6e 5d 20 44 20 77 69 74 68 20 61  ection] D with a
13530 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20   new.**         
13540 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
13550 6c 65 72 20 43 20 61 6e 64 20 61 70 70 6c 69 63  ler C and applic
13560 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
13570 65 72 20 41 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  er A..**.** {H12
13580 33 31 32 7d 20 4e 65 77 6c 79 20 63 72 65 61 74  312} Newly creat
13590 65 64 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ed [database con
135a0 6e 65 63 74 69 6f 6e 73 5d 20 73 68 61 6c 6c 20  nections] shall 
135b0 68 61 76 65 20 61 20 62 75 73 79 0a 2a 2a 20 20  have a busy.**  
135c0 20 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72 20          handler 
135d0 6f 66 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b  of NULL..**.** {
135e0 48 31 32 33 31 34 7d 20 57 68 65 6e 20 74 77 6f  H12314} When two
135f0 20 6f 72 20 6d 6f 72 65 20 5b 64 61 74 61 62 61   or more [databa
13600 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
13610 73 68 61 72 65 20 61 0a 2a 2a 20 20 20 20 20 20  share a.**      
13620 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61      [sqlite3_ena
13630 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
13640 20 7c 20 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 5d   | common cache]
13650 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
13660 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
13670 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
13680 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 75 72 72 65  connection curre
13690 6e 74 6c 79 20 75 73 69 6e 67 0a 2a 2a 20 20 20  ntly using.**   
136a0 20 20 20 20 20 20 20 74 68 65 20 63 61 63 68 65         the cache
136b0 20 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65   shall be invoke
136c0 64 20 77 68 65 6e 20 74 68 65 20 63 61 63 68 65  d when the cache
136d0 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 6c 6f   encounters a lo
136e0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31  ck..**.** {H1231
136f0 36 7d 20 49 66 20 61 20 62 75 73 79 20 68 61 6e  6} If a busy han
13700 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  dler callback re
13710 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 6e  turns zero, then
13720 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
13730 72 66 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20  rface.**        
13740 20 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20    that provoked 
13750 74 68 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  the locking even
13760 74 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 5b  t shall return [
13770 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
13780 0a 2a 2a 20 7b 48 31 32 33 31 38 7d 20 53 51 4c  .** {H12318} SQL
13790 69 74 65 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65  ite shall invoke
137a0 73 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  s the busy handl
137b0 65 72 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  er with two argu
137c0 6d 65 6e 74 73 20 77 68 69 63 68 0a 2a 2a 20 20  ments which.**  
137d0 20 20 20 20 20 20 20 20 61 72 65 20 61 20 63 6f          are a co
137e0 70 79 20 6f 66 20 74 68 65 20 70 6f 69 6e 74 65  py of the pointe
137f0 72 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68  r supplied by th
13800 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
13810 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
13820 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
13830 64 6c 65 72 28 29 5d 20 61 6e 64 20 61 20 63 6f  dler()] and a co
13840 75 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  unt of the numbe
13850 72 20 6f 66 20 70 72 69 6f 72 0a 2a 2a 20 20 20  r of prior.**   
13860 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69 6f         invocatio
13870 6e 73 20 6f 66 20 74 68 65 20 62 75 73 79 20 68  ns of the busy h
13880 61 6e 64 6c 65 72 20 66 6f 72 20 74 68 65 20 73  andler for the s
13890 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  ame locking even
138a0 74 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54  t..**.** ASSUMPT
138b0 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32  IONS:.**.** {A12
138c0 33 31 39 7d 20 41 20 62 75 73 79 20 68 61 6e 64  319} A busy hand
138d0 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
138e0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
138f0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20  connection.**   
13900 20 20 20 20 20 20 20 6f 72 20 5b 70 72 65 70 61         or [prepa
13910 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
13920 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
13930 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f  busy handler..*/
13940 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
13950 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
13960 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
13970 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  ,int), void*);..
13980 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13990 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
139a0 75 74 20 7b 48 31 32 33 34 30 7d 20 3c 53 34 30  ut {H12340} <S40
139b0 34 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  410>.**.** This 
139c0 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
139d0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
139e0 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
139f0 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73  ler] that sleeps
13a00 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66  .** for a specif
13a10 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ied amount of ti
13a20 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20  me when a table 
13a30 69 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20  is locked.  The 
13a40 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
13a50 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
13a60 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
13a70 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
13a80 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
13a90 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
13aa0 6c 61 74 65 64 2e 20 7b 48 31 32 33 34 33 7d 20  lated. {H12343} 
13ab0 41 66 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69  After "ms" milli
13ac0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
13ad0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
13ae0 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
13af0 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
13b00 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
13b10 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
13b20 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
13b30 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
13b40 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20  ..**.** Calling 
13b50 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
13b60 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
13b70 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
13b80 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
13b90 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
13ba0 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54  andlers..**.** T
13bb0 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
13bc0 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
13bd0 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72  andler for a par
13be0 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
13bf0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
13c00 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d   any any given m
13c10 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68  oment.  If anoth
13c20 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a  er busy handler.
13c30 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20  ** was defined  
13c40 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  (using [sqlite3_
13c50 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29  busy_handler()])
13c60 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
13c70 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  g.** this routin
13c80 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75  e, that other bu
13c90 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
13ca0 65 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  eared..**.** INV
13cb0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
13cc0 48 31 32 33 34 31 7d 20 54 68 65 20 5b 73 71 6c  H12341} The [sql
13cd0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
13ce0 74 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68  t()] function sh
13cf0 61 6c 6c 20 6f 76 65 72 72 69 64 65 20 61 6e 79  all override any
13d00 20 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20   prior.**       
13d10 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79     [sqlite3_busy
13d20 5f 74 69 6d 65 6f 75 74 28 29 5d 20 6f 72 20 5b  _timeout()] or [
13d30 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
13d40 64 6c 65 72 28 29 5d 20 73 65 74 74 69 6e 67 0a  dler()] setting.
13d50 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 6e 20 74  **          on t
13d60 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
13d70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
13d80 2a 0a 2a 2a 20 7b 48 31 32 33 34 33 7d 20 49 66  *.** {H12343} If
13d90 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
13da0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
13db0 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 69  usy_timeout()] i
13dc0 73 20 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20  s less than.**  
13dd0 20 20 20 20 20 20 20 20 6f 72 20 65 71 75 61 6c          or equal
13de0 20 74 6f 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74   to zero, then t
13df0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
13e00 73 68 61 6c 6c 20 62 65 20 63 6c 65 61 72 65 64  shall be cleared
13e10 20 73 6f 20 74 68 61 74 0a 2a 2a 20 20 20 20 20   so that.**     
13e20 20 20 20 20 20 61 6c 6c 20 73 75 62 73 65 71 75       all subsequ
13e30 65 6e 74 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  ent locking even
13e40 74 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 72  ts immediately r
13e50 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
13e60 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33  SY]..**.** {H123
13e70 34 34 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70  44} If the 2nd p
13e80 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
13e90 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
13ea0 74 28 29 5d 20 69 73 20 61 20 70 6f 73 69 74 69  t()] is a positi
13eb0 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  ve.**          n
13ec0 75 6d 62 65 72 20 4e 2c 20 74 68 65 6e 20 61 20  umber N, then a 
13ed0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 73 68 61  busy handler sha
13ee0 6c 6c 20 62 65 20 73 65 74 20 74 68 61 74 20 72  ll be set that r
13ef0 65 70 65 61 74 65 64 6c 79 20 63 61 6c 6c 73 0a  epeatedly calls.
13f00 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
13f10 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
13f20 69 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  in the [sqlite3_
13f30 76 66 73 20 7c 20 56 46 53 20 69 6e 74 65 72 66  vfs | VFS interf
13f40 61 63 65 5d 20 75 6e 74 69 6c 0a 2a 2a 20 20 20  ace] until.**   
13f50 20 20 20 20 20 20 20 65 69 74 68 65 72 20 74 68         either th
13f60 65 20 6c 6f 63 6b 20 63 6c 65 61 72 73 20 6f 72  e lock clears or
13f70 20 75 6e 74 69 6c 20 74 68 65 20 63 75 6d 75 6c   until the cumul
13f80 61 74 69 76 65 20 73 6c 65 65 70 20 74 69 6d 65  ative sleep time
13f90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 70  .**          rep
13fa0 6f 72 74 65 64 20 62 61 63 6b 20 62 79 20 78 53  orted back by xS
13fb0 6c 65 65 70 28 29 20 65 78 63 65 65 64 73 20 4e  leep() exceeds N
13fc0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a   milliseconds..*
13fd0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
13fe0 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74  sy_timeout(sqlit
13ff0 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f  e3*, int ms);../
14000 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
14010 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69  onvenience Routi
14020 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20  nes For Running 
14030 51 75 65 72 69 65 73 20 7b 48 31 32 33 37 30 7d  Queries {H12370}
14040 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10000>.**.** 
14050 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62  Definition: A <b
14060 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62  >result table</b
14070 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61  > is memory data
14080 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74   structure creat
14090 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71  ed by the.** [sq
140a0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
140b0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41  )] interface.  A
140c0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65   result table re
140d0 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d  cords the.** com
140e0 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75  plete query resu
140f0 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20  lts from one or 
14100 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a  more queries..**
14110 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f  .** The table co
14120 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61  nceptually has a
14130 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
14140 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75  and columns.  Bu
14150 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65  t.** these numbe
14160 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20  rs are not part 
14170 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
14180 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65  ble itself.  The
14190 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72  se.** numbers ar
141a0 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72  e obtained separ
141b0 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65  ately.  Let N be
141c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
141d0 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20  ows.** and M be 
141e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
141f0 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  lumns..**.** A r
14200 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61  esult table is a
14210 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
14220 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
14230 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
14240 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61  ings..** There a
14250 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65  re (N+1)*M eleme
14260 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79  nts in the array
14270 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70  .  The first M p
14280 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a  ointers point.**
14290 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
142a0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
142b0 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61    contain the na
142c0 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  mes of the colum
142d0 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  ns..** The remai
142e0 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c  ning entries all
142f0 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20   point to query 
14300 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76  results.  NULL v
14310 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20  alues result.** 
14320 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  in NULL pointers
14330 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  .  All other val
14340 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72  ues are in their
14350 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
14360 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
14370 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
14380 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  as returned by [
14390 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
143a0 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20  ext()]..**.** A 
143b0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67  result table mig
143c0 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e  ht consist of on
143d0 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79  e or more memory
143e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a   allocations..**
143f0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
14400 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74  to pass a result
14410 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20   table directly 
14420 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
14430 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ()]..** A result
14440 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65   table should be
14450 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69   deallocated usi
14460 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
14470 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _table()]..**.**
14480 20 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   As an example o
14490 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
144a0 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
144b0 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
144c0 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
144d0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
144e0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
144f0 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
14500 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
14510 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
14520 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
14530 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
14540 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
14550 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
14560 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
14570 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
14580 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
14590 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
145a0 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
145b0 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
145c0 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
145d0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
145e0 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
145f0 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
14600 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
14610 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
14620 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
14630 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
14640 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
14650 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
14660 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
14670 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
14680 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
14690 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
146a0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
146b0 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
146c0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
146d0 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
146e0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
146f0 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
14700 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
14710 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
14720 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
14730 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
14740 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
14750 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
14760 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
14770 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
14780 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
14790 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
147a0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e>.**.** The sql
147b0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
147c0 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
147d0 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
147e0 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
147f0 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
14800 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
14810 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
14820 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
14830 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
14840 72 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 61  r.  It returns a
14850 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
14860 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
14870 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
14880 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
14890 2a 20 41 66 74 65 72 20 74 68 65 20 63 61 6c 6c  * After the call
148a0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 68 61 73  ing function has
148b0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
148c0 74 68 65 20 72 65 73 75 6c 74 2c 20 69 74 20 73  the result, it s
148d0 68 6f 75 6c 64 0a 2a 2a 20 70 61 73 73 20 74 68  hould.** pass th
148e0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
148f0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
14900 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
14910 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
14920 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
14930 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
14940 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
14950 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
14960 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
14970 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
14980 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
14990 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
149a0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
149b0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
149c0 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
149d0 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
149e0 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
149f0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
14a00 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
14a10 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
14a20 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
14a30 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
14a40 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
14a50 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
14a60 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
14a70 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
14a80 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
14a90 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
14aa0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
14ab0 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
14ac0 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
14ad0 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
14ae0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
14af0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
14b00 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
14b10 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
14b20 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
14b30 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
14b40 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
14b50 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
14b60 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
14b70 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
14b80 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
14b90 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
14ba0 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
14bb0 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
14bc0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
14bd0 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 20 5b 73  errcode()] or [s
14be0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
14bf0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
14c00 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37  TS:.**.** {H1237
14c10 31 7d 20 49 66 20 61 20 5b 73 71 6c 69 74 65 33  1} If a [sqlite3
14c20 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 61  _get_table()] fa
14c30 69 6c 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  ils a memory all
14c40 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a  ocation, then.**
14c50 20 20 20 20 20 20 20 20 20 20 69 74 20 73 68 61            it sha
14c60 6c 6c 20 66 72 65 65 20 74 68 65 20 72 65 73 75  ll free the resu
14c70 6c 74 20 74 61 62 6c 65 20 75 6e 64 65 72 20 63  lt table under c
14c80 6f 6e 73 74 72 75 63 74 69 6f 6e 2c 20 61 62 6f  onstruction, abo
14c90 72 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  rt the.**       
14ca0 20 20 20 71 75 65 72 79 20 69 6e 20 70 72 6f 63     query in proc
14cb0 65 73 73 2c 20 73 6b 69 70 20 61 6e 79 20 73 75  ess, skip any su
14cc0 62 73 65 71 75 65 6e 74 20 71 75 65 72 69 65 73  bsequent queries
14cd0 2c 20 73 65 74 20 74 68 65 0a 2a 2a 20 20 20 20  , set the.**    
14ce0 20 20 20 20 20 20 2a 70 61 7a 52 65 73 75 6c 74        *pazResult
14cf0 20 6f 75 74 70 75 74 20 70 6f 69 6e 74 65 72 20   output pointer 
14d00 74 6f 20 4e 55 4c 4c 20 61 6e 64 20 72 65 74 75  to NULL and retu
14d10 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  rn [SQLITE_NOMEM
14d20 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 33  ]..**.** {H12373
14d30 7d 20 49 66 20 74 68 65 20 70 6e 43 6f 6c 75 6d  } If the pnColum
14d40 6e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  n parameter to [
14d50 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
14d60 65 28 29 5d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  e()] is not NULL
14d70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
14d80 6e 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 69  n a successful i
14d90 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
14da0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
14db0 29 5d 20 73 68 61 6c 6c 0a 2a 2a 20 20 20 20 20  )] shall.**     
14dc0 20 20 20 20 20 77 72 69 74 65 20 74 68 65 20 6e       write the n
14dd0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
14de0 20 69 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   in the.**      
14df0 20 20 20 20 72 65 73 75 6c 74 20 73 65 74 20 6f      result set o
14e00 66 20 74 68 65 20 71 75 65 72 79 20 69 6e 74 6f  f the query into
14e10 20 2a 70 6e 43 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a   *pnColumn..**.*
14e20 2a 20 7b 48 31 32 33 37 34 7d 20 49 66 20 74 68  * {H12374} If th
14e30 65 20 70 6e 52 6f 77 20 70 61 72 61 6d 65 74 65  e pnRow paramete
14e40 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65  r to [sqlite3_ge
14e50 74 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f  t_table()] is no
14e60 74 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20  t NULL.**       
14e70 20 20 20 74 68 65 6e 20 61 20 73 75 63 63 65 73     then a succes
14e80 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20  sful invocation 
14e90 6f 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  of [sqlite3_get_
14ea0 74 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a  table()] shall.*
14eb0 2a 20 20 20 20 20 20 20 20 20 20 77 72 69 74 65  *          write
14ec0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
14ed0 72 6f 77 73 20 69 6e 20 74 68 65 0a 2a 2a 20 20  rows in the.**  
14ee0 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20 73          result s
14ef0 65 74 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  et of the query 
14f00 69 6e 74 6f 20 2a 70 6e 52 6f 77 2e 0a 2a 2a 0a  into *pnRow..**.
14f10 2a 2a 20 7b 48 31 32 33 37 36 7d 20 41 20 73 75  ** {H12376} A su
14f20 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61 74  ccessful invocat
14f30 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
14f40 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 74 68 61  get_table()] tha
14f50 74 20 63 6f 6d 70 75 74 65 73 0a 2a 2a 20 20 20  t computes.**   
14f60 20 20 20 20 20 20 20 4e 20 72 6f 77 73 20 6f 66         N rows of
14f70 20 72 65 73 75 6c 74 20 77 69 74 68 20 43 20 63   result with C c
14f80 6f 6c 75 6d 6e 73 20 70 65 72 20 72 6f 77 20 73  olumns per row s
14f90 68 61 6c 6c 20 6d 61 6b 65 20 2a 70 61 7a 52 65  hall make *pazRe
14fa0 73 75 6c 74 0a 2a 2a 20 20 20 20 20 20 20 20 20  sult.**         
14fb0 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 72 72   point to an arr
14fc0 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
14fd0 6f 20 28 4e 2b 31 29 2a 43 20 73 74 72 69 6e 67  o (N+1)*C string
14fe0 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73  s where the firs
14ff0 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 20  t.**          C 
15000 73 74 72 69 6e 67 73 20 61 72 65 20 63 6f 6c 75  strings are colu
15010 6d 6e 20 6e 61 6d 65 73 20 61 73 20 6f 62 74 61  mn names as obta
15020 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 20 20 20  ined from.**    
15030 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
15040 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 20 61 6e  olumn_name()] an
15050 64 20 74 68 65 20 72 65 73 74 20 61 72 65 20 63  d the rest are c
15060 6f 6c 75 6d 6e 20 72 65 73 75 6c 74 20 76 61 6c  olumn result val
15070 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ues.**          
15080 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
15090 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
150a0 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  xt()]..**.** {H1
150b0 32 33 37 39 7d 20 54 68 65 20 76 61 6c 75 65 73  2379} The values
150c0 20 69 6e 20 74 68 65 20 70 61 7a 52 65 73 75 6c   in the pazResul
150d0 74 20 61 72 72 61 79 20 72 65 74 75 72 6e 65 64  t array returned
150e0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   by [sqlite3_get
150f0 5f 74 61 62 6c 65 28 29 5d 0a 2a 2a 20 20 20 20  _table()].**    
15100 20 20 20 20 20 20 73 68 61 6c 6c 20 72 65 6d 61        shall rema
15110 69 6e 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 63  in valid until c
15120 6c 65 61 72 65 64 20 62 79 20 5b 73 71 6c 69 74  leared by [sqlit
15130 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
15140 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 38 32 7d  ..**.** {H12382}
15150 20 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f   When an error o
15160 63 63 75 72 73 20 64 75 72 69 6e 67 20 65 76 61  ccurs during eva
15170 6c 75 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  luation of [sqli
15180 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
15190 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
151a0 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20   function shall 
151b0 73 65 74 20 2a 70 61 7a 52 65 73 75 6c 74 20 74  set *pazResult t
151c0 6f 20 4e 55 4c 4c 2c 20 77 72 69 74 65 20 61 6e  o NULL, write an
151d0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
151e0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 6f 20  *          into 
151f0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
15200 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
15210 6c 6c 6f 63 28 29 5d 2c 20 6d 61 6b 65 0a 2a 2a  lloc()], make.**
15220 20 20 20 20 20 20 20 20 20 20 2a 2a 70 7a 45 72            **pzEr
15230 72 6d 73 67 20 70 6f 69 6e 74 20 74 6f 20 74 68  rmsg point to th
15240 61 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  at error message
15250 2c 20 61 6e 64 20 72 65 74 75 72 6e 20 61 0a 2a  , and return a.*
15260 2a 20 20 20 20 20 20 20 20 20 20 61 70 70 72 6f  *          appro
15270 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
15280 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  de]..*/.int sqli
15290 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
152a0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
152b0 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
152c0 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
152d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
152e0 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
152f0 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
15300 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
15310 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
15320 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
15330 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
15340 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
15350 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
15360 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
15370 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
15380 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
15390 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
153a0 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
153b0 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
153c0 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
153d0 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
153e0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
153f0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
15400 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
15410 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
15420 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
15430 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
15440 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31  ng Functions {H1
15450 37 34 30 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53  7400} <S70000><S
15460 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20000>.**.** The
15470 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
15480 77 6f 72 6b 61 6c 69 6b 65 73 20 6f 66 20 74 68  workalikes of th
15490 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
154a0 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
154b0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
154c0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
154d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
154e0 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
154f0 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
15500 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
15510 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
15520 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
15530 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
15540 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
15550 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
15560 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
15570 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
15580 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
15590 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
155a0 33 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f 74 68  3_free()].  Both
155b0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
155c0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
155d0 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
155e0 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
155f0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
15600 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
15610 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
15620 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
15630 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f 73  .** In sqlite3_s
15640 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
15650 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
15660 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
15670 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
15680 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
15690 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
156a0 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
156b0 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
156c0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
156d0 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
156e0 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
156f0 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
15700 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
15710 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
15720 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
15730 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
15740 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
15750 6e 74 66 28 29 2e 20 20 54 68 69 73 20 69 73 20  ntf().  This is 
15760 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
15770 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
15780 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
15790 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
157a0 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
157b0 70 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f 74  patibility.  Not
157c0 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
157d0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
157e0 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
157f0 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
15800 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
15810 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
15820 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
15830 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
15840 68 65 20 62 75 66 66 65 72 2e 20 20 57 65 20 61  he buffer.  We a
15850 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
15860 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
15870 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
15880 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
15890 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
158a0 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
158b0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
158c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
158d0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
158e0 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
158f0 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
15900 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
15910 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
15920 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
15930 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
15940 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
15950 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
15960 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
15970 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
15980 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54 68  -terminated.  Th
15990 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
159a0 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
159b0 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
159c0 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
159d0 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
159e0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
159f0 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
15a00 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
15a10 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
15a20 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
15a30 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
15a40 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  cters..**.** The
15a50 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
15a60 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
15a70 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
15a80 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
15a90 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
15aa0 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
15ab0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
15ac0 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
15ad0 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
15ae0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
15af0 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
15b00 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
15b10 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
15b20 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  , and "%z" optio
15b30 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25 71  ns..**.** The %q
15b40 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
15b50 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
15b60 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
15b70 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ull-terminated.*
15b80 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
15b90 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
15ba0 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
15bb0 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
15bc0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
15bd0 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
15be0 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
15bf0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20 20  tring literal.  
15c00 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
15c10 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
15c20 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
15c30 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
15c40 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
15c50 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
15c60 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
15c70 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
15c80 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
15c90 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
15ca0 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
15cb0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
15cc0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
15cd0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
15ce0 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
15cf0 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
15d00 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
15d10 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
15d20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
15d30 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
15d40 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
15d50 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
15d60 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
15d70 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
15d80 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
15d90 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
15da0 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
15db0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
15dc0 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
15dd0 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
15de0 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
15df0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
15e00 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
15e10 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
15e20 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
15e30 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
15e40 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
15e50 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
15e60 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
15e70 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
15e80 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
15e90 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
15ea0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
15eb0 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
15ec0 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
15ed0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
15ee0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
15ef0 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
15f00 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
15f10 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
15f20 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
15f30 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
15f40 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
15f50 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
15f60 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
15f70 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
15f80 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
15f90 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
15fa0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
15fb0 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
15fc0 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
15fd0 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
15fe0 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
15ff0 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
16000 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
16010 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
16020 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
16030 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
16040 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  iteral..**.** Th
16050 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
16060 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
16070 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
16080 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
16090 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
160a0 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
160b0 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  tring.  Addition
160c0 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72  ally, if the par
160d0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a  ameter in the.**
160e0 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69   argument list i
160f0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
16100 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73  , %Q substitutes
16110 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22   the text "NULL"
16120 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e   (without.** sin
16130 67 6c 65 20 71 75 6f 74 65 73 29 20 69 6e 20 70  gle quotes) in p
16140 6c 61 63 65 20 6f 66 20 74 68 65 20 25 51 20 6f  lace of the %Q o
16150 70 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72 20  ption.  So, for 
16160 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
16170 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
16180 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
16190 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
161a0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
161b0 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
161c0 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
161d0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
161e0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
161f0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
16200 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
16210 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
16220 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
16230 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
16240 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
16250 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
16260 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
16270 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
16280 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
16290 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
162a0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
162b0 2a 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  * The "%z" forma
162c0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
162d0 6b 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65 20  ks exactly like 
162e0 22 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a 2a  "%s" with the.**
162f0 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
16300 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
16310 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
16320 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
16330 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
16340 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
16350 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
16360 6e 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45 4e  nput string. {EN
16370 44 7d 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  D}.**.** INVARIA
16380 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 34  NTS:.**.** {H174
16390 30 33 7d 20 20 54 68 65 20 5b 73 71 6c 69 74 65  03}  The [sqlite
163a0 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 61 6e 64  3_mprintf()] and
163b0 20 5b 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   [sqlite3_vmprin
163c0 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  tf()] interfaces
163d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
163e0 74 75 72 6e 20 65 69 74 68 65 72 20 70 6f 69 6e  turn either poin
163f0 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
16400 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
16410 72 69 6e 67 73 20 68 65 6c 64 20 69 6e 0a 2a 2a  rings held in.**
16420 20 20 20 20 20 20 20 20 20 20 20 6d 65 6d 6f 72             memor
16430 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
16440 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
16450 29 5d 20 6f 72 20 4e 55 4c 4c 20 70 6f 69 6e 74  )] or NULL point
16460 65 72 73 20 69 66 0a 2a 2a 20 20 20 20 20 20 20  ers if.**       
16470 20 20 20 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73      a call to [s
16480 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
16490 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48   fails..**.** {H
164a0 31 37 34 30 36 7d 20 20 54 68 65 20 5b 73 71 6c  17406}  The [sql
164b0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
164c0 20 69 6e 74 65 72 66 61 63 65 20 77 72 69 74 65   interface write
164d0 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
164e0 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ted.**          
164f0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 69 6e   UTF-8 string in
16500 74 6f 20 74 68 65 20 62 75 66 66 65 72 20 70 6f  to the buffer po
16510 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
16520 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16530 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 70 72  .**           pr
16540 6f 76 69 64 65 64 20 74 68 61 74 20 74 68 65 20  ovided that the 
16550 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
16560 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
16570 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  zero..**.** {H17
16580 34 30 37 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  407}  The [sqlit
16590 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
165a0 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
165b0 74 20 77 72 69 74 65 20 73 6c 6f 74 73 20 6f 66  t write slots of
165c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 69 74  .**           it
165d0 73 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  s output buffer 
165e0 28 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  (the second para
165f0 6d 65 74 65 72 29 20 6f 75 74 73 69 64 65 20 74  meter) outside t
16600 68 65 20 72 61 6e 67 65 0a 2a 2a 20 20 20 20 20  he range.**     
16610 20 20 20 20 20 20 6f 66 20 30 20 74 68 72 6f 75        of 0 throu
16620 67 68 20 4e 2d 31 20 28 77 68 65 72 65 20 4e 20  gh N-1 (where N 
16630 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
16640 61 6d 65 74 65 72 29 0a 2a 2a 20 20 20 20 20 20  ameter).**      
16650 20 20 20 20 20 72 65 67 61 72 64 6c 65 73 73 20       regardless 
16660 6f 66 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  of the length of
16670 20 74 68 65 20 73 74 72 69 6e 67 0a 2a 2a 20 20   the string.**  
16680 20 20 20 20 20 20 20 20 20 72 65 71 75 65 73 74           request
16690 65 64 20 62 79 20 74 68 65 20 66 6f 72 6d 61 74  ed by the format
166a0 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a   specification..
166b0 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  */.char *sqlite3
166c0 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
166d0 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20  har*,...);.char 
166e0 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
166f0 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
16700 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73  a_list);.char *s
16710 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
16720 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
16730 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  char*, ...);../*
16740 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
16750 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
16760 53 75 62 73 79 73 74 65 6d 20 7b 48 31 37 33 30  Subsystem {H1730
16770 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a  0} <S20000>.**.*
16780 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
16790 65 20 20 75 73 65 73 20 74 68 65 73 65 20 74 68  e  uses these th
167a0 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
167b0 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
167c0 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
167d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
167e0 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
167f0 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
16800 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
16810 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
16820 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
16830 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
16840 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
16850 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
16860 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
16870 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
16880 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
16890 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
168a0 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
168b0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
168c0 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
168d0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
168e0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
168f0 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
16900 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
16910 72 2e 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33  r..** If sqlite3
16920 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
16930 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
16940 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
16950 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
16960 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
16970 65 72 2e 20 20 49 66 20 74 68 65 20 70 61 72 61  er.  If the para
16980 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
16990 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
169a0 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
169b0 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
169c0 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
169d0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
169e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e  er..**.** Callin
169f0 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
16a00 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
16a10 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
16a20 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
16a30 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
16a40 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
16a50 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
16a60 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
16a70 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
16a80 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ed.  The sqlite3
16a90 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
16aa0 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
16ab0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
16ac0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
16ad0 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
16ae0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
16af0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
16b00 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
16b10 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
16b20 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
16b30 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
16b40 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
16b50 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
16b60 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
16b70 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
16b80 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
16b90 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
16ba0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
16bb0 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
16bc0 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
16bd0 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
16be0 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
16bf0 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
16c00 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
16c10 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
16c20 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
16c30 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
16c40 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
16c50 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
16c60 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
16c70 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
16c80 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
16c90 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63  alloc() interfac
16ca0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
16cb0 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
16cc0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
16cd0 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  n to be at least
16ce0 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20   N bytes, where 
16cf0 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f  N is the.** seco
16d00 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  nd parameter.  T
16d10 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
16d20 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a  tion to be resiz
16d30 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  ed is the first.
16d40 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  ** parameter.  I
16d50 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
16d60 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
16d70 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
16d80 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
16d90 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
16da0 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
16db0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
16dc0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77  ite3_malloc(N) w
16dd0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
16de0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
16df0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
16e00 63 28 29 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73  c()..** If the s
16e10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
16e20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
16e30 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
16e40 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
16e50 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
16e60 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
16e70 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
16e80 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
16e90 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
16ea0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
16eb0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
16ec0 63 28 29 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  c()..** sqlite3_
16ed0 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
16ee0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
16ef0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
16f00 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
16f10 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
16f20 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66  e or NULL if suf
16f30 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69  ficient memory i
16f40 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
16f50 2a 20 49 66 20 4d 20 69 73 20 74 68 65 20 73 69  * If M is the si
16f60 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
16f70 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
16f80 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
16f90 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
16fa0 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
16fb0 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
16fc0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
16fd0 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
16fe0 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
16ff0 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  c() and the prio
17000 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
17010 66 72 65 65 64 2e 0a 2a 2a 20 49 66 20 73 71 6c  freed..** If sql
17020 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
17030 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65  eturns NULL, the
17040 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  n the prior allo
17050 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74  cation.** is not
17060 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68   freed..**.** Th
17070 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
17080 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
17090 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
170a0 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
170b0 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
170c0 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
170d0 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8 byte boundary.
170e0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65   {END}.**.** The
170f0 20 64 65 66 61 75 6c 74 20 69 6d 70 6c 65 6d 65   default impleme
17100 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 6d  ntation of the m
17110 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
17120 20 73 75 62 73 79 73 74 65 6d 20 75 73 65 73 0a   subsystem uses.
17130 2a 2a 20 74 68 65 20 6d 61 6c 6c 6f 63 28 29 2c  ** the malloc(),
17140 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66   realloc() and f
17150 72 65 65 28 29 20 70 72 6f 76 69 64 65 64 20 62  ree() provided b
17160 79 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  y the standard C
17170 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 7b 48 31   library..** {H1
17180 37 33 38 32 7d 20 48 6f 77 65 76 65 72 2c 20 69  7382} However, i
17190 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
171a0 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
171b0 20 53 51 4c 49 54 45 5f 4d 45 4d 4f 52 59 5f 53   SQLITE_MEMORY_S
171c0 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 43  IZE=<i>NNN</i> C
171d0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
171e0 63 72 6f 20 28 77 68 65 72 65 20 3c 69 3e 4e 4e  cro (where <i>NN
171f0 4e 3c 2f 69 3e 0a 2a 2a 20 69 73 20 61 6e 20 69  N</i>.** is an i
17200 6e 74 65 67 65 72 29 2c 20 74 68 65 6e 20 53 51  nteger), then SQ
17210 4c 69 74 65 20 63 72 65 61 74 65 20 61 20 73 74  Lite create a st
17220 61 74 69 63 20 61 72 72 61 79 20 6f 66 20 61 74  atic array of at
17230 20 6c 65 61 73 74 0a 2a 2a 20 3c 69 3e 4e 4e 4e   least.** <i>NNN
17240 3c 2f 69 3e 20 62 79 74 65 73 20 69 6e 20 73 69  </i> bytes in si
17250 7a 65 20 61 6e 64 20 75 73 65 73 20 74 68 61 74  ze and uses that
17260 20 61 72 72 61 79 20 66 6f 72 20 61 6c 6c 20 6f   array for all o
17270 66 20 69 74 73 20 64 79 6e 61 6d 69 63 0a 2a 2a  f its dynamic.**
17280 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
17290 6f 6e 20 6e 65 65 64 73 2e 20 7b 45 4e 44 7d 20  on needs. {END} 
172a0 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f   Additional memo
172b0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 70 74  ry allocator opt
172c0 69 6f 6e 73 0a 2a 2a 20 6d 61 79 20 62 65 20 61  ions.** may be a
172d0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
172e0 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 49  eleases..**.** I
172f0 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
17300 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
17310 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
17320 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
17330 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
17340 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
17350 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
17360 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
17370 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
17380 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
17390 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
173a0 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
173b0 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
173c0 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
173d0 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
173e0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
173f0 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  an be used..**.*
17400 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53  * The Windows OS
17410 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
17420 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79   calls.** the sy
17430 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  stem malloc() an
17440 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c  d free() directl
17450 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e  y when convertin
17460 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62  g.** filenames b
17470 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38  etween the UTF-8
17480 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62   encoding used b
17490 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
174a0 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d  whatever filenam
174b0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  e encoding is us
174c0 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63  ed by the partic
174d0 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20  ular Windows.** 
174e0 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d  installation.  M
174f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
17500 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65   errors are dete
17510 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65  cted, but.** the
17520 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62  y are reported b
17530 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
17540 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
17550 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
17560 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
17570 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
17580 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a  INVARIANTS:.**.*
17590 2a 20 7b 48 31 37 33 30 33 7d 20 20 54 68 65 20  * {H17303}  The 
175a0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
175b0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
175c0 74 75 72 6e 73 20 65 69 74 68 65 72 20 61 20 70  turns either a p
175d0 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20  ointer to.**    
175e0 20 20 20 20 20 20 20 61 20 6e 65 77 6c 79 20 63         a newly c
175f0 68 65 63 6b 65 64 2d 6f 75 74 20 62 6c 6f 63 6b  hecked-out block
17600 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
17610 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ytes of memory.*
17620 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74  *           that
17630 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   is 8-byte align
17640 65 64 2c 20 6f 72 20 69 74 20 72 65 74 75 72 6e  ed, or it return
17650 73 20 4e 55 4c 4c 20 69 66 20 69 74 20 69 73 20  s NULL if it is 
17660 75 6e 61 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20  unable.**       
17670 20 20 20 20 74 6f 20 66 75 6c 66 69 6c 6c 20 74      to fulfill t
17680 68 65 20 72 65 71 75 65 73 74 2e 0a 2a 2a 0a 2a  he request..**.*
17690 2a 20 7b 48 31 37 33 30 34 7d 20 20 54 68 65 20  * {H17304}  The 
176a0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
176b0 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  N)] interface re
176c0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
176d0 6e 74 65 72 20 69 66 0a 2a 2a 20 20 20 20 20 20  nter if.**      
176e0 20 20 20 20 20 4e 20 69 73 20 6c 65 73 73 20 74       N is less t
176f0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
17700 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  zero..**.** {H17
17710 33 30 35 7d 20 20 54 68 65 20 5b 73 71 6c 69 74  305}  The [sqlit
17720 65 33 5f 66 72 65 65 28 50 29 5d 20 69 6e 74 65  e3_free(P)] inte
17730 72 66 61 63 65 20 72 65 6c 65 61 73 65 73 20 6d  rface releases m
17740 65 6d 6f 72 79 20 70 72 65 76 69 6f 75 73 6c 79  emory previously
17750 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
17760 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
17770 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
17780 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
17790 6f 63 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  oc()],.**       
177a0 20 20 20 20 6d 61 6b 69 6e 67 20 69 74 20 61 76      making it av
177b0 61 69 6c 61 62 6c 65 20 66 6f 72 20 72 65 75 73  ailable for reus
177c0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 36  e..**.** {H17306
177d0 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b 73 71  }  A call to [sq
177e0 6c 69 74 65 33 5f 66 72 65 65 28 4e 55 4c 4c 29  lite3_free(NULL)
177f0 5d 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  ] is a harmless 
17800 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  no-op..**.** {H1
17810 37 33 31 30 7d 20 20 41 20 63 61 6c 6c 20 74 6f  7310}  A call to
17820 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
17830 63 28 30 2c 4e 29 5d 20 69 73 20 65 71 75 69 76  c(0,N)] is equiv
17840 61 6c 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a  alent to a call.
17850 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 6f 20  **           to 
17860 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
17870 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33  N)]..**.** {H173
17880 31 32 7d 20 20 41 20 63 61 6c 6c 20 74 6f 20 5b  12}  A call to [
17890 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
178a0 50 2c 30 29 5d 20 69 73 20 65 71 75 69 76 61 6c  P,0)] is equival
178b0 65 6e 74 20 74 6f 20 61 20 63 61 6c 6c 0a 2a 2a  ent to a call.**
178c0 20 20 20 20 20 20 20 20 20 20 20 74 6f 20 5b 73             to [s
178d0 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d 2e  qlite3_free(P)].
178e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 31 35 7d 20  .**.** {H17315} 
178f0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
17900 20 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d   uses [sqlite3_m
17910 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
17920 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  e3_realloc()],.*
17930 2a 20 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  *           and 
17940 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
17950 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
17960 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
17970 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20  n and.**        
17980 20 20 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 20     deallocation 
17990 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  needs..**.** {H1
179a0 37 33 31 38 7d 20 20 54 68 65 20 5b 73 71 6c 69  7318}  The [sqli
179b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29  te3_realloc(P,N)
179c0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
179d0 72 6e 73 20 65 69 74 68 65 72 20 61 20 70 6f 69  rns either a poi
179e0 6e 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  nter.**         
179f0 20 20 74 6f 20 61 20 62 6c 6f 63 6b 20 6f 66 20    to a block of 
17a00 63 68 65 63 6b 65 64 2d 6f 75 74 20 6d 65 6d 6f  checked-out memo
17a10 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ry of at least N
17a20 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 0a 2a   bytes in size.*
17a30 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74  *           that
17a40 20 69 73 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   is 8-byte align
17a50 65 64 2c 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  ed, or a NULL po
17a60 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  inter..**.** {H1
17a70 37 33 32 31 7d 20 20 57 68 65 6e 20 5b 73 71 6c  7321}  When [sql
17a80 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e  ite3_realloc(P,N
17a90 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  )] returns a non
17aa0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69  -NULL pointer, i
17ab0 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20  t first.**      
17ac0 20 20 20 20 20 63 6f 70 69 65 73 20 74 68 65 20       copies the 
17ad0 66 69 72 73 74 20 4b 20 62 79 74 65 73 20 6f 66  first K bytes of
17ae0 20 63 6f 6e 74 65 6e 74 20 66 72 6f 6d 20 50 20   content from P 
17af0 69 6e 74 6f 20 74 68 65 20 6e 65 77 6c 79 0a 2a  into the newly.*
17b00 2a 20 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f  *           allo
17b10 63 61 74 65 64 20 62 6c 6f 63 6b 2c 20 77 68 65  cated block, whe
17b20 72 65 20 4b 20 69 73 20 74 68 65 20 6c 65 73 73  re K is the less
17b30 65 72 20 6f 66 20 4e 20 61 6e 64 20 74 68 65 20  er of N and the 
17b40 73 69 7a 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20  size of.**      
17b50 20 20 20 20 20 74 68 65 20 62 75 66 66 65 72 20       the buffer 
17b60 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 32 32  P..**.** {H17322
17b70 7d 20 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  }  When [sqlite3
17b80 5f 72 65 61 6c 6c 6f 63 28 50 2c 4e 29 5d 20 72  _realloc(P,N)] r
17b90 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 4e 55 4c  eturns a non-NUL
17ba0 4c 20 70 6f 69 6e 74 65 72 2c 20 69 74 20 66 69  L pointer, it fi
17bb0 72 73 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rst.**          
17bc0 20 72 65 6c 65 61 73 65 73 20 74 68 65 20 62 75   releases the bu
17bd0 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ffer P..**.** {H
17be0 31 37 33 32 33 7d 20 20 57 68 65 6e 20 5b 73 71  17323}  When [sq
17bf0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c  lite3_realloc(P,
17c00 4e 29 5d 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  N)] returns NULL
17c10 2c 20 74 68 65 20 62 75 66 66 65 72 20 50 20 69  , the buffer P i
17c20 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6e  s.**           n
17c30 6f 74 20 6d 6f 64 69 66 69 65 64 20 6f 72 20 72  ot modified or r
17c40 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 41  eleased..**.** A
17c50 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  SSUMPTIONS:.**.*
17c60 2a 20 7b 41 31 37 33 35 30 7d 20 20 54 68 65 20  * {A17350}  The 
17c70 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
17c80 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
17c90 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
17ca0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
17cb0 20 20 20 20 20 20 20 20 20 20 20 6d 75 73 74 20             must 
17cc0 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
17cd0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
17ce0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
17cf0 70 72 69 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  prior.**        
17d00 20 20 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66     invocation of
17d10 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
17d20 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
17d30 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
17d40 68 61 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  have.**         
17d50 20 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72    not yet been r
17d60 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  eleased..**.** {
17d70 41 31 37 33 35 31 7d 20 20 54 68 65 20 61 70 70  A17351}  The app
17d80 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
17d90 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
17da0 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 20  any part of.**  
17db0 20 20 20 20 20 20 20 20 20 61 20 62 6c 6f 63 6b           a block
17dc0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
17dd0 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
17de0 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20  eased using.**  
17df0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
17e00 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
17e10 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
17e20 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
17e30 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
17e40 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
17e50 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
17e60 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
17e70 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  free(void*);../*
17e80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
17e90 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53  mory Allocator S
17ea0 74 61 74 69 73 74 69 63 73 20 7b 48 31 37 33 37  tatistics {H1737
17eb0 30 7d 20 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a  0} <S30210>.**.*
17ec0 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
17ed0 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
17ee0 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
17ef0 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
17f00 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
17f10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
17f20 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
17f30 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
17f40 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
17f50 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
17f60 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
17f70 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
17f80 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
17f90 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
17fa0 2a 0a 2a 2a 20 7b 48 31 37 33 37 31 7d 20 54 68  *.** {H17371} Th
17fb0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
17fc0 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
17fd0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
17fe0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
17ff0 20 20 20 20 20 20 20 20 20 20 6f 66 20 6d 65 6d            of mem
18000 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
18010 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
18020 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
18030 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37  d)..**.** {H1737
18040 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
18050 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
18060 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
18070 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a  rns the maximum.
18080 2a 2a 20 20 20 20 20 20 20 20 20 20 76 61 6c 75  **          valu
18090 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65  e of [sqlite3_me
180a0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e  mory_used()] sin
180b0 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  ce the high-wate
180c0 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20  r mark.**       
180d0 20 20 20 77 61 73 20 6c 61 73 74 20 72 65 73 65     was last rese
180e0 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 34  t..**.** {H17374
180f0 7d 20 54 68 65 20 76 61 6c 75 65 73 20 72 65 74  } The values ret
18100 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
18110 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
18120 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
18130 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
18140 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
18150 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
18160 61 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  ad.**          a
18170 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
18180 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
18190 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
181a0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20  _malloc()],.**  
181b0 20 20 20 20 20 20 20 20 62 75 74 20 6e 6f 74 20          but not 
181c0 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
181d0 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
181e0 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
181f0 61 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ary.**          
18200 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
18210 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
18220 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
18230 20 7b 48 31 37 33 37 35 7d 20 54 68 65 20 6d 65   {H17375} The me
18240 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
18250 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
18260 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
18270 75 65 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  ue of.**        
18280 20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72    [sqlite3_memor
18290 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
182a0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
182b0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20  ameter to.**    
182c0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d        [sqlite3_m
182d0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
182e0 29 5d 20 69 73 20 74 72 75 65 2e 20 20 54 68 65  )] is true.  The
182f0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
18300 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 5b  **          by [
18310 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
18320 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
18330 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
18340 61 72 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ark.**          
18350 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
18360 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  et..*/.sqlite3_i
18370 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
18380 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a  ory_used(void);.
18390 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
183a0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
183b0 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
183c0 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
183d0 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
183e0 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
183f0 65 72 61 74 6f 72 20 7b 48 31 37 33 39 30 7d 20  erator {H17390} 
18400 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53  <S20000>.**.** S
18410 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61  QLite contains a
18420 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73   high-quality ps
18430 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62  eudo-random numb
18440 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52  er generator (PR
18450 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73  NG) used to.** s
18460 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 52 4f 57  elect random ROW
18470 49 44 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69  IDs when inserti
18480 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
18490 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
184a0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
184b0 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
184c0 73 69 62 6c 65 20 52 4f 57 49 44 2e 20 20 54 68  sible ROWID.  Th
184d0 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
184e0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
184f0 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
18500 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
18510 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
18520 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
18530 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
18540 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
18550 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
18560 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
18570 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
18580 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
18590 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
185a0 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
185b0 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  to buffer P..**.
185c0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69 6d  ** The first tim
185d0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
185e0 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65  s invoked (eithe
185f0 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20  r internally or 
18600 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  by.** the applic
18610 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20  ation) the PRNG 
18620 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  is seeded using 
18630 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
18640 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ned.** from the 
18650 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
18660 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
18670 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
18680 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c  object..** On al
18690 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  l subsequent inv
186a0 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73  ocations, the ps
186b0 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
186c0 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
186d0 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
186e0 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
186f0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
18700 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
18710 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a  .** method..**.*
18720 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
18730 0a 2a 2a 20 7b 48 31 37 33 39 32 7d 20 54 68 65  .** {H17392} The
18740 20 5b 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d   [sqlite3_random
18750 6e 65 73 73 28 4e 2c 50 29 5d 20 69 6e 74 65 72  ness(N,P)] inter
18760 66 61 63 65 20 77 72 69 74 65 73 20 4e 20 62 79  face writes N by
18770 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  tes of.**       
18780 20 20 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20     high-quality 
18790 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
187a0 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
187b0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
187c0 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
187d0 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
187e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
187f0 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
18800 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
18810 6b 73 20 7b 48 31 32 35 30 30 7d 20 3c 53 37 30  ks {H12500} <S70
18820 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  100>.**.** This 
18830 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
18840 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63  s a authorizer c
18850 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
18860 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
18870 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18880 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  n], supplied in 
18890 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
188a0 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  nt..** The autho
188b0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
188c0 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
188d0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
188e0 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
188f0 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
18900 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
18910 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
18920 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
18930 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
18940 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
18950 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
18960 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72 69  _v2()].  At vari
18970 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
18980 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
18990 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
189a0 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
189b0 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
189c0 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
189d0 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
189e0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
189f0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
18a00 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
18a10 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
18a20 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  .  The authorize
18a30 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
18a40 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
18a50 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
18a60 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
18a70 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
18a80 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
18a90 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
18aa0 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
18ab0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
18ac0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
18ad0 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
18ae0 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
18af0 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
18b00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
18b10 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
18b20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
18b30 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
18b40 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
18b50 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
18b60 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
18b70 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
18b80 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
18b90 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
18ba0 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
18bb0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
18bc0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
18bd0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
18be0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
18bf0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
18c00 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
18c10 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
18c20 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
18c30 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
18c40 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
18c50 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
18c60 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68 65  sted is ok.  Whe
18c70 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
18c80 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44  eturns [SQLITE_D
18c90 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71  ENY], the.** [sq
18ca0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
18cb0 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
18cc0 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
18cd0 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74  gered the.** aut
18ce0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
18cf0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
18d00 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69  message explaini
18d10 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73  ng that.** acces
18d20 73 20 69 73 20 64 65 6e 69 65 64 2e 20 20 49 66  s is denied.  If
18d30 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
18d40 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
18d50 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
18d60 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
18d70 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
18d80 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
18d90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
18da0 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
18db0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
18dc0 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
18dd0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
18de0 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
18df0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
18e00 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
18e10 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
18e20 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
18e30 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
18e40 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
18e50 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
18e60 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
18e70 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
18e80 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
18e90 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
18ea0 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  table..**.** The
18eb0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
18ec0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
18ed0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
18ee0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
18ef0 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
18f00 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
18f10 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
18f20 69 6e 74 65 72 66 61 63 65 2e 20 54 68 65 20 73  interface. The s
18f30 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
18f40 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
18f50 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
18f60 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
18f70 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
18f80 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
18f90 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
18fa0 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
18fb0 72 69 7a 65 64 2e 20 54 68 65 20 74 68 69 72 64  rized. The third
18fc0 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
18fd0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
18fe0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
18ff0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
19000 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
19010 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
19020 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
19030 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
19040 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
19050 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
19060 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
19070 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
19080 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
19090 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
190a0 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
190b0 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
190c0 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
190d0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
190e0 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
190f0 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
19100 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
19110 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
19120 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
19130 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
19140 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
19150 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
19160 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
19170 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
19180 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
19190 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
191a0 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
191b0 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
191c0 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
191d0 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
191e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
191f0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
19200 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
19210 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
19220 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
19230 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
19240 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
19250 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
19260 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
19270 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
19280 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
19290 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
192a0 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
192b0 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
192c0 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
192d0 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
192e0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
192f0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
19300 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
19310 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
19320 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
19330 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
19340 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
19350 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
19360 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
19370 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
19380 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
19390 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
193a0 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
193b0 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
193c0 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
193d0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
193e0 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e 67  *.** Only a sing
193f0 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
19400 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
19410 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
19420 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
19430 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
19440 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
19450 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
19460 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
19470 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 73 61 62  ous call.  Disab
19480 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  le the authorize
19490 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20  r by installing 
194a0 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e  a NULL callback.
194b0 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
194c0 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  er is disabled b
194d0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
194e0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
194f0 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
19500 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
19510 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
19520 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
19530 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
19540 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f  nvoked the autho
19550 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a  rizer callback..
19560 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
19570 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
19580 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
19590 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
195a0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
195b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
195c0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
195d0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
195e0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
195f0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 5b 73 71  ..**.** When [sq
19600 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
19610 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70  ()] is used to p
19620 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
19630 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  nt, the.** state
19640 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65  ment might be re
19650 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
19660 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
19670 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
19680 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
19690 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
196a0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
196b0 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
196c0 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
196d0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
196e0 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
196f0 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
19700 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e  step()]..**.** N
19710 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
19720 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
19730 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
19740 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
19750 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
19760 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
19770 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
19780 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
19790 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
197a0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
197b0 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
197c0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
197d0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
197e0 35 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  501} The [sqlite
197f0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
19800 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61  (D,...)] interfa
19810 63 65 20 72 65 67 69 73 74 65 72 73 20 61 0a 2a  ce registers a.*
19820 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 68 6f  *          autho
19830 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
19840 69 74 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ith database con
19850 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  nection D..**.**
19860 20 7b 48 31 32 35 30 32 7d 20 54 68 65 20 61 75   {H12502} The au
19870 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
19880 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
19890 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
198a0 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62  re.**          b
198b0 65 69 6e 67 20 70 61 72 73 65 65 64 20 61 6e 64  eing parseed and
198c0 20 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a   compiled..**.**
198d0 20 7b 48 31 32 35 30 33 7d 20 49 66 20 74 68 65   {H12503} If the
198e0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
198f0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 6e 79  back returns any
19900 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
19910 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53  n.**          [S
19920 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
19930 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
19940 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
19950 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  en.**          t
19960 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
19970 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 74 68  nterface call th
19980 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 20 20 20  at caused.**    
19990 20 20 20 20 20 20 74 68 65 20 61 75 74 68 6f 72        the author
199a0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f  izer callback to
199b0 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c 20   run shall fail 
199c0 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20 20  with an.**      
199d0 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f      [SQLITE_ERRO
199e0 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  R] error code an
199f0 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  d an appropriate
19a00 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
19a10 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 34 7d 20 57  **.** {H12504} W
19a20 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hen the authoriz
19a30 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
19a40 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
19a50 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
19a60 2a 20 20 20 20 20 20 20 20 20 20 64 65 73 63 72  *          descr
19a70 69 62 65 64 20 69 73 20 70 72 6f 63 65 73 73 65  ibed is processe
19a80 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a 2a  d normally..**.*
19a90 2a 20 7b 48 31 32 35 30 35 7d 20 57 68 65 6e 20  * {H12505} When 
19aa0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
19ab0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
19ac0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
19ad0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  he.**          a
19ae0 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 74 65 72  pplication inter
19af0 66 61 63 65 20 63 61 6c 6c 20 74 68 61 74 20 63  face call that c
19b00 61 75 73 65 64 20 74 68 65 0a 2a 2a 20 20 20 20  aused the.**    
19b10 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65 72        authorizer
19b20 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75 6e   callback to run
19b30 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20   shall fail.**  
19b40 20 20 20 20 20 20 20 20 77 69 74 68 20 61 6e 20          with an 
19b50 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 65  [SQLITE_ERROR] e
19b60 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61 6e  rror code and an
19b70 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a   error message.*
19b80 2a 20 20 20 20 20 20 20 20 20 20 65 78 70 6c 61  *          expla
19b90 69 6e 69 6e 67 20 74 68 61 74 20 61 63 63 65 73  ining that acces
19ba0 73 20 69 73 20 64 65 6e 69 65 64 2e 0a 2a 2a 0a  s is denied..**.
19bb0 2a 2a 20 7b 48 31 32 35 30 36 7d 20 49 66 20 74  ** {H12506} If t
19bc0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  he authorizer co
19bd0 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72 61  de (the 2nd para
19be0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
19bf0 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20 20  horizer.**      
19c00 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69 73      callback) is
19c10 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61   [SQLITE_READ] a
19c20 6e 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  nd the authorize
19c30 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
19c40 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  ns.**          [
19c50 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
19c60 74 68 65 6e 20 74 68 65 20 70 72 65 70 61 72 65  then the prepare
19c70 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  d statement is c
19c80 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 0a 2a 2a  onstructed to.**
19c90 20 20 20 20 20 20 20 20 20 20 69 6e 73 65 72 74            insert
19ca0 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
19cb0 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
19cc0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
19cd0 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 20 20  would have.**   
19ce0 20 20 20 20 20 20 20 62 65 65 6e 20 72 65 61 64         been read
19cf0 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
19d00 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
19d10 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 37  d..**.** {H12507
19d20 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69  } If the authori
19d30 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32 6e  zer code (the 2n
19d40 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
19d50 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a 2a  he authorizer.**
19d60 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62 61            callba
19d70 63 6b 29 20 69 73 20 61 6e 79 74 68 69 6e 67 20  ck) is anything 
19d80 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
19d90 54 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e 0a 2a  TE_READ], then.*
19da0 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65 74  *          a ret
19db0 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  urn of [SQLITE_I
19dc0 47 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 20 73  GNORE] has the s
19dd0 61 6d 65 20 65 66 66 65 63 74 20 61 73 20 5b 53  ame effect as [S
19de0 51 4c 49 54 45 5f 44 45 4e 59 5d 2e 0a 2a 2a 0a  QLITE_DENY]..**.
19df0 2a 2a 20 7b 48 31 32 35 31 30 7d 20 54 68 65 20  ** {H12510} The 
19e00 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
19e10 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
19e20 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
19e30 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20 20  copy of.**      
19e40 20 20 20 20 74 68 65 20 74 68 69 72 64 20 70 61      the third pa
19e50 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
19e60 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
19e70 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
19e80 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35  ace..**.** {H125
19e90 31 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70  11} The second p
19ea0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
19eb0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
19ec0 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20 20  nteger.**       
19ed0 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20     [SQLITE_COPY 
19ee0 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
19ef0 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68  hat specifies th
19f00 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
19f10 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ion.**          
19f20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
19f30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 32 7d  ..**.** {H12512}
19f40 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75   The third throu
19f50 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  gh sixth paramet
19f60 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ers to the callb
19f70 61 63 6b 20 61 72 65 0a 2a 2a 20 20 20 20 20 20  ack are.**      
19f80 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
19f90 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
19fa0 20 63 6f 6e 74 61 69 6e 0a 2a 2a 20 20 20 20 20   contain.**     
19fb0 20 20 20 20 20 61 64 64 69 74 69 6f 6e 61 6c 20       additional 
19fc0 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
19fd0 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
19fe0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
19ff0 20 7b 48 31 32 35 32 30 7d 20 45 61 63 68 20 63   {H12520} Each c
1a000 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
1a010 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1a020 5d 20 6f 76 65 72 72 69 64 65 73 0a 2a 2a 20 20  ] overrides.**  
1a030 20 20 20 20 20 20 20 20 61 6e 79 20 70 72 65 76          any prev
1a040 69 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c 65 64  iously installed
1a050 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
1a060 2a 2a 20 7b 48 31 32 35 32 31 7d 20 41 20 4e 55  ** {H12521} A NU
1a070 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d 65  LL authorizer me
1a080 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74 68  ans that no auth
1a090 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20 20  orization.**    
1a0a0 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20 69        callback i
1a0b0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
1a0c0 20 7b 48 31 32 35 32 32 7d 20 54 68 65 20 64 65   {H12522} The de
1a0d0 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65 72  fault authorizer
1a0e0 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   is NULL..*/.int
1a0f0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1a100 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
1a110 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
1a120 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
1a130 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1a140 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1a150 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
1a160 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
1a170 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
1a180 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1a190 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b 48   Return Codes {H
1a1a0 31 32 35 39 30 7d 20 3c 48 31 32 35 30 30 3e 0a  12590} <H12500>.
1a1b0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1a1c0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1a1d0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
1a1e0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1a1f0 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
1a200 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
1a210 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
1a220 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
1a230 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
1a240 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
1a250 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1a260 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
1a270 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
1a280 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
1a290 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1a2a0 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
1a2b0 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
1a2c0 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
1a2d0 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  tion..*/.#define
1a2e0 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31   SQLITE_DENY   1
1a2f0 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20     /* Abort the 
1a300 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
1a310 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23  th an error */.#
1a320 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47  define SQLITE_IG
1a330 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27  NORE 2   /* Don'
1a340 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20  t allow access, 
1a350 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61  but don't genera
1a360 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a  te an error */..
1a370 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a380 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f  Authorizer Actio
1a390 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 35 30 7d  n Codes {H12550}
1a3a0 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H12500>.**.** 
1a3b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
1a3c0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
1a3d0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
1a3e0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
1a3f0 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
1a400 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
1a410 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
1a420 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
1a430 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
1a440 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
1a450 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
1a460 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
1a470 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
1a480 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
1a490 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
1a4a0 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
1a4b0 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
1a4c0 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
1a4d0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1a4e0 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
1a4f0 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
1a500 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
1a510 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
1a520 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
1a530 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
1a540 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
1a550 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
1a560 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
1a570 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
1a580 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
1a590 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
1a5a0 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
1a5b0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
1a5c0 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
1a5d0 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
1a5e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1a5f0 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 61  ter.  The 5th pa
1a600 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
1a610 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  * authorizer cal
1a620 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d  lback is the nam
1a630 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
1a640 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e ("main", "temp
1a650 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61  ",.** etc.) if a
1a660 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 20  pplicable.  The 
1a670 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
1a680 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1a690 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
1a6a0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
1a6b0 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
1a6c0 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
1a6d0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
1a6e0 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
1a6f0 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
1a700 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
1a710 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
1a720 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
1a730 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
1a740 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
1a750 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 31 7d 20  .**.** {H12551} 
1a760 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1a770 65 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 20 20  eter to an.**   
1a780 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1a790 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
1a7a0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1a7b0 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20 61  back] shall be a
1a7c0 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20  n integer.**    
1a7d0 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f        [SQLITE_CO
1a7e0 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  PY | authorizer 
1a7f0 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69  code] that speci
1a800 66 69 65 73 20 77 68 61 74 20 61 63 74 69 6f 6e  fies what action
1a810 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
1a820 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
1a830 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 32 7d  ..**.** {H12552}
1a840 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
1a850 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
1a860 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
1a870 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1a880 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
1a890 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 5d  zation callback]
1a8a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61  .**          sha
1a8b0 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
1a8c0 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
1a8d0 6e 67 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 20  ng on which.**  
1a8e0 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f          [SQLITE_
1a8f0 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65  COPY | authorize
1a900 72 20 63 6f 64 65 5d 20 69 73 20 75 73 65 64 20  r code] is used 
1a910 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1a920 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
1a930 48 31 32 35 35 33 7d 20 54 68 65 20 35 74 68 20  H12553} The 5th 
1a940 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1a950 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1a960 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1a970 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1a980 72 20 63 61 6c 6c 62 61 63 6b 5d 20 73 68 61 6c  r callback] shal
1a990 6c 20 62 65 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  l be the name.**
1a9a0 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
1a9b0 20 64 61 74 61 62 61 73 65 20 28 65 78 61 6d 70   database (examp
1a9c0 6c 65 3a 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d  le: "main", "tem
1a9d0 70 22 2c 20 65 74 63 2e 29 20 69 66 20 61 70 70  p", etc.) if app
1a9e0 6c 69 63 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b  licable..**.** {
1a9f0 48 31 32 35 35 34 7d 20 54 68 65 20 36 74 68 20  H12554} The 6th 
1aa00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1aa10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1aa20 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1aa30 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1aa40 72 20 63 61 6c 6c 62 61 63 6b 5d 20 73 68 61 6c  r callback] shal
1aa50 6c 20 62 65 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  l be the name.**
1aa60 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68 65            of the
1aa70 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
1aa80 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
1aa90 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
1aaa0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
1aab0 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
1aac0 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
1aad0 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
1aae0 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
1aaf0 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  om.**          t
1ab00 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
1ab10 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..*/./*********
1ab20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ab30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ab40 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
1ab50 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
1ab60 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
1ab70 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
1ab80 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
1ab90 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1aba0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1abb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1abc0 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
1abd0 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
1abe0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1abf0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ac00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ac10 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
1ac20 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
1ac30 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1ac40 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1ac50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ac60 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
1ac70 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
1ac80 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1ac90 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1aca0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1acb0 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
1acc0 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
1acd0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1ace0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1acf0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1ad00 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
1ad10 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
1ad20 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1ad30 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1ad40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1ad50 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
1ad60 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
1ad70 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1ad80 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1ad90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1ada0 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
1adb0 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
1adc0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1add0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1ade0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
1adf0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
1ae00 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
1ae10 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1ae20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1ae30 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1ae40 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
1ae50 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
1ae60 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1ae70 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1ae80 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1ae90 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
1aea0 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
1aeb0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1aec0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1aed0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1aee0 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
1aef0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1af00 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1af10 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1af20 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1af30 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
1af40 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1af50 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1af60 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1af70 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1af80 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
1af90 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1afa0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1afb0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1afc0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1afd0 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
1afe0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1aff0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1b000 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b010 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
1b020 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
1b030 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1b040 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1b050 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b060 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
1b070 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
1b080 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1b090 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1b0a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b0b0 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
1b0c0 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
1b0d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b0e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b0f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b100 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
1b110 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
1b120 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
1b130 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
1b140 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b150 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
1b160 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
1b170 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
1b180 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
1b190 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b1a0 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
1b1b0 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
1b1c0 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
1b1d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1b1e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
1b1f0 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
1b200 20 20 20 20 32 32 20 20 20 2f 2a 20 4e 55 4c 4c      22   /* NULL
1b210 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
1b220 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1b230 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
1b240 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
1b250 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
1b260 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
1b270 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
1b280 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
1b290 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
1b2a0 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
1b2b0 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
1b2c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1b2d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
1b2e0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
1b2f0 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
1b300 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
1b310 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b320 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
1b330 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1b340 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
1b350 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
1b360 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1b370 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
1b380 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
1b390 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
1b3a0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1b3b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1b3c0 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
1b3d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
1b3e0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1b3f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1b400 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b410 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
1b420 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
1b430 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1b440 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
1b450 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b460 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
1b470 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
1b480 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1b490 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
1b4a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b4b0 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
1b4c0 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
1b4d0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
1b4e0 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65     Function Name
1b4f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b500 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
1b510 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
1b520 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
1b530 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1b540 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
1b550 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
1b560 69 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c 53  ions {H12280} <S
1b570 36 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  60400>.** EXPERI
1b580 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65  MENTAL.**.** The
1b590 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
1b5a0 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
1b5b0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
1b5c0 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
1b5d0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
1b5e0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
1b5f0 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
1b600 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ments..**.** The
1b610 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1b620 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
1b630 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1b640 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
1b650 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
1b660 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
1b670 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
1b680 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
1b690 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63  tep()]..** The c
1b6a0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1b6b0 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
1b6c0 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61  g of the SQL sta
1b6d0 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61  tement text.** a
1b6e0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1b6f0 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
1b700 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  cuting.  Additio
1b710 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63  nal callbacks oc
1b720 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
1b730 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
1b740 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
1b750 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
1b760 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
1b770 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
1b780 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
1b790 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
1b7a0 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  rigger..**.** Th
1b7b0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1b7c0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1b7d0 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
1b7e0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
1b7f0 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
1b800 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
1b810 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63  .  The profile c
1b820 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
1b830 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
1b840 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
1b850 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
1b860 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
1b870 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
1b880 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
1b890 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a   took to run..**
1b8a0 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1b8b0 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 31 7d 20 54  **.** {H12281} T
1b8c0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1b8d0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
1b8e0 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  by [sqlite3_trac
1b8f0 65 28 29 5d 20 0a 2a 2a 20 20 20 20 20 20 20 20  e()] .**        
1b900 20 20 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b    shall be invok
1b910 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  ed.**          w
1b920 68 65 6e 65 76 65 72 20 61 6e 20 53 51 4c 20 73  henever an SQL s
1b930 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
1b940 65 67 69 6e 73 20 74 6f 20 65 78 65 63 75 74 65  egins to execute
1b950 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
1b960 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 69 67   whenever a trig
1b970 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 20 66  ger subprogram f
1b980 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20 72  irst begins to r
1b990 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38  un..**.** {H1228
1b9a0 32 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  2} Each call to 
1b9b0 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
1b9c0 5d 20 73 68 61 6c 6c 20 6f 76 65 72 72 69 64 65  ] shall override
1b9d0 20 74 68 65 20 70 72 65 76 69 6f 75 73 6c 79 0a   the previously.
1b9e0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
1b9f0 73 74 65 72 65 64 20 74 72 61 63 65 20 63 61 6c  stered trace cal
1ba00 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  lback..**.** {H1
1ba10 32 32 38 33 7d 20 41 20 4e 55 4c 4c 20 74 72 61  2283} A NULL tra
1ba20 63 65 20 63 61 6c 6c 62 61 63 6b 20 73 68 61 6c  ce callback shal
1ba30 6c 20 64 69 73 61 62 6c 65 20 74 72 61 63 69 6e  l disable tracin
1ba40 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 34  g..**.** {H12284
1ba50 7d 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  } The first argu
1ba60 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63  ment to the trac
1ba70 65 20 63 61 6c 6c 62 61 63 6b 20 73 68 61 6c 6c  e callback shall
1ba80 20 62 65 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   be a copy of.**
1ba90 20 20 20 20 20 20 20 20 20 20 74 68 65 20 70 6f            the po
1baa0 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
1bab0 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  the 3rd argument
1bac0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
1bad0 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ce()]..**.** {H1
1bae0 32 32 38 35 7d 20 54 68 65 20 73 65 63 6f 6e 64  2285} The second
1baf0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
1bb00 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
1bb10 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  is a.**         
1bb20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1bb30 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 63 6f   UTF-8 string co
1bb40 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6f 72 69  ntaining the ori
1bb50 67 69 6e 61 6c 20 74 65 78 74 0a 2a 2a 20 20 20  ginal text.**   
1bb60 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 53 51         of the SQ
1bb70 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69  L statement as i
1bb80 74 20 77 61 73 20 70 61 73 73 65 64 20 69 6e 74  t was passed int
1bb90 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
1bba0 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20  re_v2()].**     
1bbb0 20 20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69       or the equi
1bbc0 76 61 6c 65 6e 74 2c 20 6f 72 20 61 6e 20 53 51  valent, or an SQ
1bbd0 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e 64 69 63 61  L comment indica
1bbe0 74 69 6e 67 20 74 68 65 20 62 65 67 69 6e 6e 69  ting the beginni
1bbf0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ng.**          o
1bc00 66 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70  f a trigger subp
1bc10 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  rogram..**.** {H
1bc20 31 32 32 38 37 7d 20 54 68 65 20 63 61 6c 6c 62  12287} The callb
1bc30 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1bc40 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69  istered by [sqli
1bc50 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 69  te3_profile()] i
1bc60 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20  s invoked.**    
1bc70 20 20 20 20 20 20 61 73 20 65 61 63 68 20 53 51        as each SQ
1bc80 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
1bc90 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  shes..**.** {H12
1bca0 32 38 38 7d 20 54 68 65 20 66 69 72 73 74 20 70  288} The first p
1bcb0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1bcc0 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
1bcd0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
1bce0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 33 72            the 3r
1bcf0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
1bd00 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1bd10 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38  )]..**.** {H1228
1bd20 39 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  9} The second pa
1bd30 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70  rameter to the p
1bd40 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
1bd50 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  is a.**         
1bd60 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1bd70 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
1bd80 61 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  at contains the 
1bd90 63 6f 6d 70 6c 65 74 65 20 74 65 78 74 20 6f 66  complete text of
1bda0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1bdb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1bdc0 73 20 69 74 20 77 61 73 20 70 72 6f 63 65 73 73  s it was process
1bdd0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ed by [sqlite3_p
1bde0 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20  repare_v2()].** 
1bdf0 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
1be00 65 71 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a  equivalent..**.*
1be10 2a 20 7b 48 31 32 32 39 30 7d 20 54 68 65 20 74  * {H12290} The t
1be20 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
1be30 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61  o the profile ca
1be40 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 65 73 74  llback is an est
1be50 69 6d 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  imate.**        
1be60 20 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20    of the number 
1be70 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 20 6f  of nanoseconds o
1be80 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
1be90 65 20 72 65 71 75 69 72 65 64 20 74 6f 0a 2a 2a  e required to.**
1bea0 20 20 20 20 20 20 20 20 20 20 72 75 6e 20 74 68            run th
1beb0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1bec0 66 72 6f 6d 20 73 74 61 72 74 20 74 6f 20 66 69  from start to fi
1bed0 6e 69 73 68 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nish..*/.SQLITE_
1bee0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
1bef0 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
1bf00 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
1bf10 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
1bf20 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
1bf30 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45  d*);.SQLITE_EXPE
1bf40 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
1bf50 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
1bf60 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
1bf70 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
1bf80 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
1bf90 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
1bfa0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1bfb0 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
1bfc0 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
1bfd0 20 7b 48 31 32 39 31 30 7d 20 3c 53 36 30 34 30   {H12910} <S6040
1bfe0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
1bff0 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73  utine configures
1c000 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
1c010 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72  tion - the.** pr
1c020 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
1c030 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  - that is invoke
1c040 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
1c050 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75  uring long.** ru
1c060 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b  nning calls to [
1c070 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
1c080 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1c090 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1c0a0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20  3_get_table()]. 
1c0b0 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
1c0c0 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
1c0d0 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
1c0e0 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
1c0f0 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
1c100 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ery..**.** If th
1c110 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
1c120 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
1c130 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
1c140 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
1c150 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
1c160 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
1c170 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
1c180 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
1c190 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
1c1a0 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
1c1b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
1c1c0 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  ess handler must
1c1d0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
1c1e0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
1c1f0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
1c200 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1c210 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
1c220 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
1c230 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
1c240 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1c250 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1c260 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
1c270 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
1c280 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c290 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
1c2a0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
1c2b0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
1c2c0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1c2d0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31  TS:.**.** {H1291
1c2e0 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  1} The callback 
1c2f0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1c300 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
1c310 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1c320 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  ).**          is
1c330 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
1c340 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
1c350 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
1c360 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
1c370 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1c380 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 32 7d 20  .**.** {H12912} 
1c390 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  The progress cal
1c3a0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1c3b0 20 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20   once for every 
1c3c0 4e 20 76 69 72 74 75 61 6c 0a 2a 2a 20 20 20 20  N virtual.**    
1c3d0 20 20 20 20 20 20 6d 61 63 68 69 6e 65 20 6f 70        machine op
1c3e0 63 6f 64 65 73 2c 20 77 68 65 72 65 20 4e 20 69  codes, where N i
1c3f0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
1c400 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20  ument to.**     
1c410 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
1c420 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1c430 65 72 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  er()] call that 
1c440 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20  registered.**   
1c450 20 20 20 20 20 20 20 74 68 65 20 63 61 6c 6c 62         the callb
1c460 61 63 6b 2e 20 20 49 66 20 4e 20 69 73 20 6c 65  ack.  If N is le
1c470 73 73 20 74 68 61 6e 20 31 2c 20 73 71 6c 69 74  ss than 1, sqlit
1c480 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1c490 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 20 20 20  ler().**        
1c4a0 20 20 61 63 74 73 20 61 73 20 69 66 20 61 20 4e    acts as if a N
1c4b0 55 4c 4c 20 70 72 6f 67 72 65 73 73 20 68 61 6e  ULL progress han
1c4c0 64 6c 65 72 20 68 61 64 20 62 65 65 6e 20 73 70  dler had been sp
1c4d0 65 63 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  ecified..**.** {
1c4e0 48 31 32 39 31 33 7d 20 54 68 65 20 70 72 6f 67  H12913} The prog
1c4f0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 74  ress callback it
1c500 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66 69  self is identifi
1c510 65 64 20 62 79 20 74 68 65 20 74 68 69 72 64 0a  ed by the third.
1c520 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 67 75  **          argu
1c530 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1c540 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1c550 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31  ()..**.** {H1291
1c560 34 7d 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  4} The fourth ar
1c570 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1c580 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1c590 65 72 28 29 20 69 73 20 61 0a 2a 2a 20 20 20 20  er() is a.**    
1c5a0 20 20 20 20 20 20 76 6f 69 64 20 70 6f 69 6e 74        void point
1c5b0 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
1c5c0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
1c5d0 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  ck.**          f
1c5e0 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74 69 6d  unction each tim
1c5f0 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e  e it is invoked.
1c600 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 35 7d 20  .**.** {H12915} 
1c610 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  If a call to [sq
1c620 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
1c630 73 75 6c 74 73 20 69 6e 20 66 65 77 65 72 20 74  sults in fewer t
1c640 68 61 6e 20 4e 20 6f 70 63 6f 64 65 73 0a 2a 2a  han N opcodes.**
1c650 20 20 20 20 20 20 20 20 20 20 62 65 69 6e 67 20            being 
1c660 65 78 65 63 75 74 65 64 2c 20 74 68 65 6e 20 74  executed, then t
1c670 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
1c680 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e  back is never in
1c690 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  voked..**.** {H1
1c6a0 32 39 31 36 7d 20 45 76 65 72 79 20 63 61 6c 6c  2916} Every call
1c6b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f   to [sqlite3_pro
1c6c0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d  gress_handler()]
1c6d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65  .**          ove
1c6e0 72 77 72 69 74 65 73 20 61 6e 79 20 70 72 65 76  rwrites any prev
1c6f0 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65  iously registere
1c700 64 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  d progress handl
1c710 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31  er..**.** {H1291
1c720 37 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65  7} If the progre
1c730 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  ss handler callb
1c740 61 63 6b 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ack is NULL then
1c750 20 6e 6f 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20   no progress.** 
1c760 20 20 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72           handler
1c770 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
1c780 2a 2a 20 7b 48 31 32 39 31 38 7d 20 49 66 20 74  ** {H12918} If t
1c790 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
1c7a0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 72  back returns a r
1c7b0 65 73 75 6c 74 20 6f 74 68 65 72 20 74 68 61 6e  esult other than
1c7c0 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20   0, then.**     
1c7d0 20 20 20 20 20 74 68 65 20 62 65 68 61 76 69 6f       the behavio
1c7e0 72 20 69 73 20 61 20 69 66 20 5b 73 71 6c 69 74  r is a if [sqlit
1c7f0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20  e3_interrupt()] 
1c800 68 61 64 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e  had been called.
1c810 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 53 33  .**          <S3
1c820 30 35 30 30 3e 0a 2a 2f 0a 76 6f 69 64 20 73 71  0500>.*/.void sq
1c830 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1c840 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1c850 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
1c860 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
1c870 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
1c880 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
1c890 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
1c8a0 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32 30 30  {H12700} <S40200
1c8b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
1c8c0 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
1c8d0 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
1c8e0 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69  ile whose name i
1c8f0 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a  s given by the.*
1c900 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
1c910 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61 6d  ent. The filenam
1c920 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
1c930 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
1c940 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
1c950 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1c960 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
1c970 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
1c980 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
1c990 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
1c9a0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 41  ite3_open16(). A
1c9b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c9c0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
1c9d0 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
1c9e0 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
1c9f0 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
1ca00 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
1ca10 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
1ca20 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
1ca30 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1ca40 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
1ca50 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
1ca60 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
1ca70 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
1ca80 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
1ca90 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
1caa0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
1cab0 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
1cac0 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  . If the databas
1cad0 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
1cae0 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
1caf0 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
1cb00 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
1cb10 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
1cb20 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
1cb30 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
1cb40 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  ed.  The.** [sql
1cb50 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
1cb60 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
1cb70 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
1cb80 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
1cb90 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
1cba0 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
1cbb0 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
1cbc0 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  error..**.** The
1cbd0 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
1cbe0 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  g for the databa
1cbf0 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  se will be UTF-8
1cc00 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   if.** sqlite3_o
1cc10 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
1cc20 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61  _open_v2() is ca
1cc30 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d  lled and.** UTF-
1cc40 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1cc50 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73   byte order if s
1cc60 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
1cc70 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
1cc80 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
1cc90 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
1cca0 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
1ccb0 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
1ccc0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
1ccd0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1cce0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
1ccf0 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
1cd00 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
1cd10 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
1cd20 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
1cd30 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
1cd40 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
1cd50 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1cd60 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
1cd70 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
1cd80 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
1cd90 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
1cda0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
1cdb0 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
1cdc0 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
1cdd0 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
1cde0 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
1cdf0 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67  ction.  The flag
1ce00 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  s parameter can 
1ce10 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
1ce20 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
1ce30 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
1ce40 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
1ce50 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
1ce60 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
1ce70 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ] or [SQLITE_OPE
1ce80 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
1ce90 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  gs:.**.** <dl>.*
1cea0 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  * <dt>[SQLITE_OP
1ceb0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
1cec0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1ced0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1cee0 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
1cef0 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
1cf00 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
1cf10 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
1cf20 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1cf30 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
1cf40 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1cf50 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
1cf60 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
1cf70 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
1cf80 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
1cf90 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
1cfa0 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
1cfb0 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
1cfc0 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
1cfd0 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
1cfe0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
1cff0 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
1d000 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
1d010 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
1d020 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
1d030 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1d040 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  d.</dd>.**.** <d
1d050 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1d060 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
1d070 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
1d080 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1d090 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1d0a0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
1d0b0 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
1d0c0 20 69 73 20 63 72 65 61 74 65 73 20 69 74 20 69   is creates it i
1d0d0 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
1d0e0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
1d0f0 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
1d100 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
1d110 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
1d120 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1d130 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
1d140 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64  6().</dd>.** </d
1d150 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
1d160 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
1d170 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1d180 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
1d190 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
1d1a0 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
1d1b0 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   or one of the c
1d1c0 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
1d1d0 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64  n above combined
1d1e0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
1d1f0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1d200 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  X] or [SQLITE_OP
1d210 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
1d220 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ags,.** then the
1d230 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
1d240 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
1d250 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1d260 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
1d270 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
1d280 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1d290 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
1d2a0 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
1d2b0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1d2c0 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
1d2d0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
1d2e0 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
1d2f0 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
1d300 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
1d310 74 2d 74 69 6d 65 2e 20 20 49 66 20 74 68 65 0a  t-time.  If the.
1d320 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1d330 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
1d340 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
1d350 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d360 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
1d370 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
1d380 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
1d390 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
1d3a0 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
1d3b0 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
1d3c0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
1d3d0 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
1d3e0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65  *.** If the file
1d3f0 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
1d400 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
1d410 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
1d420 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
1d430 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
1d440 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
1d450 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  n.  This in-memo
1d460 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
1d470 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
1d480 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1d490 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
1d4a0 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
1d4b0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
1d4c0 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
1d4d0 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
1d4e0 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
1d4f0 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
1d500 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
1d510 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
1d520 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
1d530 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
1d540 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
1d550 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
1d560 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
1d570 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
1d580 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
1d590 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
1d5a0 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
1d5b0 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
1d5c0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ity..**.** If th
1d5d0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
1d5e0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
1d5f0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1d600 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
1d610 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
1d620 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 54  l be created.  T
1d630 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
1d640 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
1d650 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
1d660 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
1d670 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1d680 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1d690 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ed..**.** The fo
1d6a0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
1d6b0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1d6c0 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
1d6d0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
1d6e0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
1d6f0 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
1d700 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1d710 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
1d720 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
1d730 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
1d740 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20 74  hould use.  If t
1d750 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1d760 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
1d770 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
1d780 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1d790 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
1d7a0 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  s used..**.** <b
1d7b0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
1d7c0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
1d7d0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
1d7e0 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
1d7f0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
1d800 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1d810 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
1d820 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
1d830 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
1d840 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
1d850 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
1d860 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
1d870 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
1d880 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
1d890 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
1d8a0 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
1d8b0 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
1d8c0 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
1d8d0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1d8e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1d8f0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1d900 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30  TS:.**.** {H1270
1d910 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1d920 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
1d930 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
1d940 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1d950 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1d960 20 69 6e 74 65 72 66 61 63 65 73 20 63 72 65 61   interfaces crea
1d970 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20  te a new.**     
1d980 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
1d990 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63  onnection] assoc
1d9a0 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20 20  iated with.**   
1d9b0 20 20 20 20 20 20 20 74 68 65 20 64 61 74 61 62         the datab
1d9c0 61 73 65 20 66 69 6c 65 20 67 69 76 65 6e 20 69  ase file given i
1d9d0 6e 20 74 68 65 69 72 20 66 69 72 73 74 20 70 61  n their first pa
1d9e0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
1d9f0 48 31 32 37 30 32 7d 20 54 68 65 20 66 69 6c 65  H12702} The file
1da00 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
1da10 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1da20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20  UTF-8.**        
1da30 20 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f    for [sqlite3_o
1da40 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  pen()] and [sqli
1da50 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61  te3_open_v2()] a
1da60 6e 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20  nd as UTF-16.** 
1da70 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65 20           in the 
1da80 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1da90 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  r for [sqlite3_o
1daa0 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  pen16()]..**.** 
1dab0 7b 48 31 32 37 30 33 7d 20 41 20 73 75 63 63 65  {H12703} A succe
1dac0 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
1dad0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   of [sqlite3_ope
1dae0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
1daf0 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20  pen16()],.**    
1db00 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
1db10 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 72 69  3_open_v2()] wri
1db20 74 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  tes a pointer to
1db30 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20   a new.**       
1db40 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
1db50 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a 70  nection] into *p
1db60 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  pDb..**.** {H127
1db70 30 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  04} The [sqlite3
1db80 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1db90 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
1dba0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
1dbb0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1dbc0 5d 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74  ] interfaces ret
1dbd0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
1dbe0 75 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a 2a 2a  upon success,.**
1dbf0 20 20 20 20 20 20 20 20 20 20 6f 72 20 61 6e 20            or an 
1dc00 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
1dc10 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c  or code] on fail
1dc20 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ure..**.** {H127
1dc30 30 36 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20  06} The default 
1dc40 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  text encoding fo
1dc50 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65  r a new database
1dc60 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
1dc70 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1dc80 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b  te3_open()] or [
1dc90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1dca0 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  )] will be UTF-8
1dcb0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 37 7d  ..**.** {H12707}
1dcc0 20 54 68 65 20 64 65 66 61 75 6c 74 20 74 65 78   The default tex
1dcd0 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61  t encoding for a
1dce0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 72   new database cr
1dcf0 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20  eated using.**  
1dd00 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1dd10 5f 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c 6c 20  _open16()] will 
1dd20 62 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  be UTF-16..**.**
1dd30 20 7b 48 31 32 37 30 39 7d 20 54 68 65 20 5b 73   {H12709} The [s
1dd40 71 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c 44 29  qlite3_open(F,D)
1dd50 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65  ] interface is e
1dd60 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a 20  quivalent to.** 
1dd70 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1dd80 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c  3_open_v2(F,D,G,
1dd90 30 29 5d 20 77 68 65 72 65 20 74 68 65 20 47 20  0)] where the G 
1dda0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
1ddb0 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
1ddc0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1ddd0 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  |[SQLITE_OPEN_CR
1dde0 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  EATE]..**.** {H1
1ddf0 32 37 31 31 7d 20 49 66 20 74 68 65 20 47 20 70  2711} If the G p
1de00 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
1de10 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
1de20 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20  ,G,V)] contains 
1de30 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1de40 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  bit value [SQLIT
1de50 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
1de60 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1de70 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20  se is opened.** 
1de80 20 20 20 20 20 20 20 20 20 66 6f 72 20 72 65 61           for rea
1de90 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  ding only..**.**
1dea0 20 7b 48 31 32 37 31 32 7d 20 49 66 20 74 68 65   {H12712} If the
1deb0 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   G parameter to 
1dec0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1ded0 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61  (F,D,G,V)] conta
1dee0 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ins the.**      
1def0 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53      bit value [S
1df00 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1df10 52 49 54 45 5d 20 74 68 65 6e 20 74 68 65 20 64  RITE] then the d
1df20 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1df30 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
1df40 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1df50 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
1df60 72 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e  r for reading on
1df70 6c 79 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20  ly if the.**    
1df80 20 20 20 20 20 20 66 69 6c 65 20 69 73 20 77 72        file is wr
1df90 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
1dfa0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1dfb0 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ystem..**.** {H1
1dfc0 32 37 31 33 7d 20 49 66 20 74 68 65 20 47 20 70  2713} If the G p
1dfd0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
1dfe0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
1dff0 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74 68 65  ,G,V)] omits the
1e000 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74  .**          bit
1e010 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f   value [SQLITE_O
1e020 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20  PEN_CREATE] and 
1e030 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
1e040 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20  s not.**        
1e050 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69    previously exi
1e060 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
1e070 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1e080 7b 48 31 32 37 31 34 7d 20 49 66 20 74 68 65 20  {H12714} If the 
1e090 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  G parameter to [
1e0a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1e0b0 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69  F,D,G,V)] contai
1e0c0 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
1e0d0 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51     bit value [SQ
1e0e0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1e0f0 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  ] and the databa
1e100 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20  se does not.**  
1e110 20 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 73          previous
1e120 6c 79 20 65 78 69 73 74 2c 20 74 68 65 6e 20 61  ly exist, then a
1e130 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
1e140 65 20 74 6f 20 63 72 65 61 74 65 20 61 6e 64 0a  e to create and.
1e150 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 69 74  **          init
1e160 69 61 6c 69 7a 65 20 74 68 65 20 64 61 74 61 62  ialize the datab
1e170 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ase..**.** {H127
1e180 31 37 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e  17} If the filen
1e190 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ame argument to 
1e1a0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1e1b0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
1e1c0 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  6()],.**        
1e1d0 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70    or [sqlite3_op
1e1e0 65 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a 6d 65  en_v2()] is ":me
1e1f0 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20  mory:", then an 
1e200 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20  private,.**     
1e210 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c 2c 20       ephemeral, 
1e220 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
1e230 73 65 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  se is created fo
1e240 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
1e250 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74  ..**          <t
1e260 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50  odo>Is SQLITE_OP
1e270 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45  EN_CREATE|SQLITE
1e280 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
1e290 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20  required.**     
1e2a0 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f       in sqlite3_
1e2b0 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f  open_v2()?</todo
1e2c0 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 39 7d  >.**.** {H12719}
1e2d0 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   If the filename
1e2e0 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65   is NULL or an e
1e2f0 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
1e300 6e 20 61 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20  n a private,.** 
1e310 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65 72           ephemer
1e320 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  al on-disk datab
1e330 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
1e340 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ted..**         
1e350 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45   <todo>Is SQLITE
1e360 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c  _OPEN_CREATE|SQL
1e370 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1e380 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20  TE required.**  
1e390 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74          in sqlit
1e3a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74  e3_open_v2()?</t
1e3b0 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  odo>.**.** {H127
1e3c0 32 31 7d 20 54 68 65 20 5b 64 61 74 61 62 61 73  21} The [databas
1e3d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 72  e connection] cr
1e3e0 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eated by [sqlite
1e3f0 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c  3_open_v2(F,D,G,
1e400 56 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  V)].**          
1e410 77 69 6c 6c 20 75 73 65 20 74 68 65 20 5b 73 71  will use the [sq
1e420 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1e430 74 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  t identified by 
1e440 74 68 65 20 56 20 70 61 72 61 6d 65 74 65 72 2c  the V parameter,
1e450 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
1e460 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1e470 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1e480 20 69 66 20 56 20 69 73 20 61 20 4e 55 4c 4c 20   if V is a NULL 
1e490 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  pointer..**.** {
1e4a0 48 31 32 37 32 33 7d 20 54 77 6f 20 5b 64 61 74  H12723} Two [dat
1e4b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e4c0 73 5d 20 77 69 6c 6c 20 73 68 61 72 65 20 61 20  s] will share a 
1e4d0 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 20 69 66 20  common cache if 
1e4e0 62 6f 74 68 20 77 65 72 65 0a 2a 2a 20 20 20 20  both were.**    
1e4f0 20 20 20 20 20 20 6f 70 65 6e 65 64 20 77 69 74        opened wit
1e500 68 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 77  h the same VFS w
1e510 68 69 6c 65 20 5b 73 68 61 72 65 64 20 63 61 63  hile [shared cac
1e520 68 65 20 6d 6f 64 65 5d 20 77 61 73 20 65 6e 61  he mode] was ena
1e530 62 6c 65 64 20 61 6e 64 0a 2a 2a 20 20 20 20 20  bled and.**     
1e540 20 20 20 20 20 69 66 20 62 6f 74 68 20 66 69 6c       if both fil
1e550 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72 65 20 65  enames compare e
1e560 71 75 61 6c 20 75 73 69 6e 67 20 6d 65 6d 63 6d  qual using memcm
1e570 70 28 29 20 61 66 74 65 72 20 68 61 76 69 6e 67  p() after having
1e580 20 62 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   been.**        
1e590 20 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 74    processed by t
1e5a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  he [sqlite3_vfs 
1e5b0 7c 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 5d  | xFullPathname]
1e5c0 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 56   method of the V
1e5d0 46 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  FS..*/.int sqlit
1e5e0 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
1e5f0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
1e600 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
1e610 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
1e620 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
1e630 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
1e640 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
1e650 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
1e660 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
1e670 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
1e680 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
1e690 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
1e6a0 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
1e6b0 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
1e6c0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
1e6d0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
1e6e0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1e6f0 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
1e700 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
1e710 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
1e720 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
1e730 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
1e740 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
1e750 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
1e760 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
1e770 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
1e780 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
1e790 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
1e7a0 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
1e7b0 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
1e7c0 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
1e7d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
1e7e0 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
1e7f0 73 61 67 65 73 20 7b 48 31 32 38 30 30 7d 20 3c  sages {H12800} <
1e800 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S60200>.**.** Th
1e810 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
1e820 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
1e830 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
1e840 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
1e850 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
1e860 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
1e870 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1e880 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
1e890 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
1e8a0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
1e8b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1e8c0 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
1e8d0 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
1e8e0 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
1e8f0 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
1e900 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
1e910 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
1e920 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
1e930 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
1e940 69 6e 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74  ined.  The sqlit
1e950 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
1e960 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ode().** interfa
1e970 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65  ce is the same e
1e980 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
1e990 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
1e9a0 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72   .** [extended r
1e9b0 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e  esult code] even
1e9c0 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72   when extended r
1e9d0 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a  esult codes are.
1e9e0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  ** disabled..**.
1e9f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
1ea00 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
1ea10 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
1ea20 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
1ea30 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
1ea40 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
1ea50 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
1ea60 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1ea70 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
1ea80 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** Memory to ho
1ea90 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
1eaa0 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
1eab0 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
1eac0 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
1ead0 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
1eae0 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
1eaf0 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
1eb00 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
1eb10 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
1eb20 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
1eb30 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
1eb40 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
1eb50 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
1eb60 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
1eb70 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
1eb80 6e 73 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ns..**.** When t
1eb90 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
1eba0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
1ebb0 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
1ebc0 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
1ebd0 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
1ebe0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
1ebf0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1ec00 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
1ec10 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
1ec20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
1ec30 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
1ec40 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
1ec50 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
1ec60 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
1ec70 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
1ec80 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
1ec90 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
1eca0 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
1ecb0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
1ecc0 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
1ecd0 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
1ece0 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
1ecf0 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
1ed00 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1ed10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
1ed20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
1ed30 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
1ed40 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
1ed50 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
1ed60 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
1ed70 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
1ed80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
1ed90 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
1eda0 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
1edb0 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
1edc0 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
1edd0 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
1ede0 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
1edf0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
1ee00 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
1ee10 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
1ee20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
1ee30 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
1ee40 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
1ee50 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
1ee60 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
1ee70 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
1ee80 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
1ee90 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
1eea0 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  not be set..**.*
1eeb0 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1eec0 0a 2a 2a 20 7b 48 31 32 38 30 31 7d 20 54 68 65  .** {H12801} The
1eed0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1eee0 65 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(D)] interface 
1eef0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
1ef00 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ric.**          
1ef10 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
1ef20 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
1ef30 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
1ef40 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a 2a 2a  most recently.**
1ef50 20 20 20 20 20 20 20 20 20 20 66 61 69 6c 65 64            failed
1ef60 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20   interface call 
1ef70 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1ef80 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
1ef90 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
1efa0 2a 2a 20 7b 48 31 32 38 30 32 7d 20 54 68 65 20  ** {H12802} The 
1efb0 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
1efc0 64 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69 6e  d_errcode(D)] in
1efd0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1efe0 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20  the numeric.**  
1eff0 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65          [extende
1f000 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
1f010 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
1f020 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ntly.**         
1f030 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63   failed interfac
1f040 65 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  e call associate
1f050 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
1f060 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1f070 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30   D..**.** {H1280
1f080 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
1f090 65 72 72 6d 73 67 28 44 29 5d 20 61 6e 64 20 5b  errmsg(D)] and [
1f0a0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1f0b0 28 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  (D)].**         
1f0c0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75   interfaces retu
1f0d0 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
1f0e0 61 67 65 20 74 65 78 74 20 74 68 61 74 20 64 65  age text that de
1f0f0 73 63 72 69 62 65 73 0a 2a 2a 20 20 20 20 20 20  scribes.**      
1f100 20 20 20 20 74 68 65 20 65 72 72 6f 72 20 69 6e      the error in
1f110 20 74 68 65 20 6d 6f 73 74 6c 79 20 72 65 63 65   the mostly rece
1f120 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e 74 65  ntly failed inte
1f130 72 66 61 63 65 20 63 61 6c 6c 2c 0a 2a 2a 20 20  rface call,.**  
1f140 20 20 20 20 20 20 20 20 65 6e 63 6f 64 65 64 20          encoded 
1f150 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
1f160 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63  or UTF-16 respec
1f170 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tively..**.** {H
1f180 31 32 38 30 37 7d 20 54 68 65 20 73 74 72 69 6e  12807} The strin
1f190 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  gs returned by [
1f1a0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1f1b0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  ] and [sqlite3_e
1f1c0 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20  rrmsg16()].**   
1f1d0 20 20 20 20 20 20 20 61 72 65 20 76 61 6c 69 64         are valid
1f1e0 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
1f1f0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
1f200 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   call..**.** {H1
1f210 32 38 30 38 7d 20 43 61 6c 6c 73 20 74 6f 20 41  2808} Calls to A
1f220 50 49 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  PI routines that
1f230 20 64 6f 20 6e 6f 74 20 72 65 74 75 72 6e 20 61   do not return a
1f240 6e 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  n error code.** 
1f250 20 20 20 20 20 20 20 20 20 28 65 78 61 6d 70 6c           (exampl
1f260 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  e: [sqlite3_data
1f270 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f 20 6e 6f  _count()]) do no
1f280 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 68  t.**          ch
1f290 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72 20 63  ange the error c
1f2a0 6f 64 65 20 6f 72 20 6d 65 73 73 61 67 65 20 72  ode or message r
1f2b0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20  eturned by.**   
1f2c0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1f2d0 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c  errcode()], [sql
1f2e0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
1f2f0 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20  rcode()],.**    
1f300 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
1f310 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71  rrmsg()], or [sq
1f320 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1f330 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 39  ]..**.** {H12809
1f340 7d 20 49 6e 74 65 72 66 61 63 65 73 20 74 68 61  } Interfaces tha
1f350 74 20 61 72 65 20 6e 6f 74 20 61 73 73 6f 63 69  t are not associ
1f360 61 74 65 64 20 77 69 74 68 20 61 20 73 70 65 63  ated with a spec
1f370 69 66 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20  ific.**         
1f380 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1f390 63 74 69 6f 6e 5d 20 28 65 78 61 6d 70 6c 65 73  ction] (examples
1f3a0 3a 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  :.**          [s
1f3b0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
1f3c0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e  ] or [sqlite3_en
1f3d0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
1f3e0 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  e()].**         
1f3f0 20 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65 20 74   do not change t
1f400 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1f410 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
1f420 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f    [sqlite3_errco
1f430 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  de()], [sqlite3_
1f440 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
1f450 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
1f460 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1f470 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
1f480 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f  _errmsg16()]..*/
1f490 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72  .int sqlite3_err
1f4a0 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
1f4b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  );.int sqlite3_e
1f4c0 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
1f4d0 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f  sqlite3 *db);.co
1f4e0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1f4f0 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33  3_errmsg(sqlite3
1f500 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
1f510 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1f520 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1f530 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
1f540 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
1f550 74 20 7b 48 31 33 30 30 30 7d 20 3c 48 31 33 30  t {H13000} <H130
1f560 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  10>.** KEYWORDS:
1f570 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
1f580 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
1f590 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
1f5a0 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
1f5b0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
1f5c0 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
1f5d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
1f5e0 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
1f5f0 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
1f600 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
1f610 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
1f620 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
1f630 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
1f640 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
1f650 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
1f660 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
1f670 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
1f680 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
1f690 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
1f6a0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
1f6b0 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
1f6c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1f6d0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
1f6e0 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
1f6f0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
1f700 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
1f710 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
1f720 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
1f730 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
1f740 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
1f750 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
1f760 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
1f770 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f780 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
1f790 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
1f7a0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
1f7b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
1f7c0 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
1f7d0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
1f7e0 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
1f7f0 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
1f800 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
1f810 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
1f820 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1f830 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
1f840 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
1f850 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
1f860 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
1f870 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
1f880 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1f890 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
1f8a0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
1f8b0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
1f8c0 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
1f8d0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
1f8e0 69 6d 65 20 4c 69 6d 69 74 73 20 7b 48 31 32 37  ime Limits {H127
1f8f0 36 30 7d 20 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a  60} <S20600>.**.
1f900 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1f910 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
1f920 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
1f930 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
1f940 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
1f950 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
1f960 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
1f970 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1f980 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
1f990 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f9a0 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
1f9b0 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
1f9c0 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
1f9d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1f9e0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
1f9f0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
1fa00 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
1fa10 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
1fa20 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
1fa30 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
1fa40 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
1fa50 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
1fa60 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
1fa70 73 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e  struct.  The fun
1fa80 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1fa90 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a  e old limit..**.
1faa0 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 20 6c 69  ** If the new li
1fab0 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
1fac0 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
1fad0 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
1fae0 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d  ..** For the lim
1faf0 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20 53  it category of S
1fb00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20  QLITE_LIMIT_XYZ 
1fb10 74 68 65 72 65 20 69 73 20 61 20 68 61 72 64 20  there is a hard 
1fb20 75 70 70 65 72 0a 2a 2a 20 62 6f 75 6e 64 20 73  upper.** bound s
1fb30 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d  et by a compile-
1fb40 74 69 6d 65 20 43 20 70 72 65 70 72 6f 63 65 73  time C preproces
1fb50 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20  sor macro named 
1fb60 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a  SQLITE_MAX_XYZ..
1fb70 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
1fb80 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
1fb90 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
1fba0 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74  X_".).** Attempt
1fbb0 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
1fbc0 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
1fbd0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
1fbe0 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
1fbf0 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
1fc00 65 20 68 61 72 64 20 75 70 70 65 72 20 6c 69 6d  e hard upper lim
1fc10 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69  it..**.** Run ti
1fc20 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
1fc30 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
1fc40 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
1fc50 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
1fc60 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
1fc70 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
1fc80 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
1fc90 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
1fca0 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
1fcb0 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
1fcc0 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
1fcd0 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
1fce0 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
1fcf0 62 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61  bbrowser that ha
1fd00 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
1fd10 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
1fd20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
1fd30 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
1fd40 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
1fd50 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
1fd60 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
1fd70 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
1fd80 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
1fd90 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
1fda0 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
1fdb0 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
1fdc0 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
1fdd0 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
1fde0 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
1fdf0 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
1fe00 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
1fe10 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
1fe20 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
1fe30 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
1fe40 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
1fe50 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
1fe60 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
1fe70 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1fe80 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
1fe90 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
1fea0 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
1feb0 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
1fec0 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
1fed0 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
1fee0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
1fef0 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
1ff00 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
1ff10 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
1ff20 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
1ff30 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
1ff40 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
1ff50 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
1ff60 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
1ff70 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  es..**.** INVARI
1ff80 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
1ff90 37 36 32 7d 20 41 20 73 75 63 63 65 73 73 66 75  762} A successfu
1ffa0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
1ffb0 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d  e3_limit(D,C,V)]
1ffc0 20 77 68 65 72 65 20 56 20 69 73 0a 2a 2a 20 20   where V is.**  
1ffd0 20 20 20 20 20 20 20 20 70 6f 73 69 74 69 76 65          positive
1ffe0 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 69 6d   changes the lim
1fff0 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f  it on the size o
20000 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e  f construct C in
20010 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
20020 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
20030 63 74 69 6f 6e 5d 20 44 20 74 6f 20 74 68 65 20  ction] D to the 
20040 6c 65 73 73 65 72 20 6f 66 20 56 20 61 6e 64 20  lesser of V and 
20050 74 68 65 20 68 61 72 64 20 75 70 70 65 72 0a 2a  the hard upper.*
20060 2a 20 20 20 20 20 20 20 20 20 20 62 6f 75 6e 64  *          bound
20070 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20   on the size of 
20080 43 20 74 68 61 74 20 69 73 20 73 65 74 20 61 74  C that is set at
20090 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 0a 2a   compile-time..*
200a0 2a 0a 2a 2a 20 7b 48 31 32 37 36 36 7d 20 41 20  *.** {H12766} A 
200b0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
200c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  to [sqlite3_limi
200d0 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20  t(D,C,V)] where 
200e0 56 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  V is negative.**
200f0 20 20 20 20 20 20 20 20 20 20 6c 65 61 76 65 73            leaves
20100 20 74 68 65 20 73 74 61 74 65 20 6f 66 20 74 68   the state of th
20110 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
20120 65 63 74 69 6f 6e 5d 20 44 20 75 6e 63 68 61 6e  ection] D unchan
20130 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ged..**.** {H127
20140 36 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  69} A successful
20150 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
20160 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20  3_limit(D,C,V)] 
20170 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20  returns the.**  
20180 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
20190 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68   the limit on th
201a0 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72  e size of constr
201b0 75 63 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20  uct C in the.** 
201c0 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
201d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
201e0 20 61 73 20 69 74 20 77 61 73 20 70 72 69 6f 72   as it was prior
201f0 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 0a 2a 2f   to the call..*/
20200 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d  .int sqlite3_lim
20210 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  it(sqlite3*, int
20220 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29   id, int newVal)
20230 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20240 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69  F: Run-Time Limi
20250 74 20 43 61 74 65 67 6f 72 69 65 73 20 7b 48 31  t Categories {H1
20260 32 37 39 30 7d 20 3c 48 31 32 37 36 30 3e 0a 2a  2790} <H12760>.*
20270 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
20280 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 6c 69  it category} {li
20290 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a  mit categories}.
202a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
202b0 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
202c0 69 6f 75 73 20 61 73 70 65 63 74 73 20 6f 66 20  ious aspects of 
202d0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
202e0 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20  ection].** that 
202f0 63 61 6e 20 62 65 20 6c 69 6d 69 74 65 64 20 69  can be limited i
20300 6e 20 73 69 7a 65 20 62 79 20 63 61 6c 6c 73 20  n size by calls 
20310 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  to [sqlite3_limi
20320 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 6d 65 61  t()]..** The mea
20330 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
20340 69 6f 75 73 20 6c 69 6d 69 74 73 20 61 72 65 20  ious limits are 
20350 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
20360 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
20370 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
20380 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
20390 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
203a0 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
203b0 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
203c0 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  w.<dd>.**.** <dt
203d0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  >SQLITE_LIMIT_SQ
203e0 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  L_LENGTH</dt>.**
203f0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
20400 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51   length of an SQ
20410 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  L statement.</dd
20420 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
20430 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
20440 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
20450 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
20460 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
20470 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
20480 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
20490 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c  ult set of a SEL
204a0 45 43 54 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  ECT or the maxim
204b0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
204c0 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
204d0 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
204e0 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
204f0 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a  Y clause.</dd>.*
20500 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
20510 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
20520 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
20530 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
20540 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
20550 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
20560 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
20570 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
20580 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
20590 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
205a0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
205b0 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
205c0 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
205d0 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  tement.</dd>.**.
205e0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
205f0 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
20600 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
20610 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
20620 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
20630 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
20640 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
20650 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
20660 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  SQL statement.</
20670 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
20680 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
20690 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
206a0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
206b0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
206c0 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
206d0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
206e0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
206f0 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
20700 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
20710 6e 75 6d 62 65 72 20 6f 66 20 61 74 74 61 63 68  number of attach
20720 65 64 20 64 61 74 61 62 61 73 65 73 2e 3c 2f 64  ed databases.</d
20730 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
20740 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
20750 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
20760 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
20770 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
20780 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
20790 6d 65 6e 74 20 74 6f 20 74 68 65 20 4c 49 4b 45  ment to the LIKE
207a0 20 6f 72 0a 2a 2a 20 47 4c 4f 42 20 6f 70 65 72   or.** GLOB oper
207b0 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ators.</dd>.**.*
207c0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
207d0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
207e0 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
207f0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
20800 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69  r of variables i
20810 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
20820 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62  nt that can.** b
20830 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a  e bound.</dd>.**
20840 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
20850 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
20860 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
20870 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
20880 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
20890 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
208a0 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
208b0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
208c0 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
208d0 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
208e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
208f0 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
20900 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
20910 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
20920 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
20930 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
20940 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
20950 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
20960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
20970 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
20980 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
20990 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
209a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
209b0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
209c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
209d0 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
209e0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
209f0 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
20a00 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
20a10 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
20a20 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
20a30 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    9../*.** CAPI3
20a40 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
20a50 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
20a60 7b 48 31 33 30 31 30 7d 20 3c 53 31 30 30 30 30  {H13010} <S10000
20a70 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
20a80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
20a90 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f  mpiler}.**.** To
20aa0 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
20ab0 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
20ac0 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
20ad0 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
20ae0 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
20af0 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
20b00 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
20b10 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
20b20 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
20b30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20b40 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
20b50 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 63 61  om a.** prior ca
20b60 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
20b70 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
20b80 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 20 5b  _open_v2()] or [
20b90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
20ba0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  ]..**.** The sec
20bb0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
20bc0 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
20bd0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
20be0 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
20bf0 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
20c00 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
20c10 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
20c20 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
20c30 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
20c40 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
20c50 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
20c60 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
20c70 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
20c80 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
20c90 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66  UTF-16..**.** If
20ca0 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
20cb0 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ent is less than
20cc0 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c   zero, then zSql
20cd0 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
20ce0 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
20cf0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 49 66 20   terminator. If 
20d00 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
20d10 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  ative, then it i
20d20 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
20d30 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65   number of  byte
20d40 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
20d50 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73  .  When nByte is
20d60 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
20d70 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
20d80 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
20d90 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
20da0 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
20db0 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
20dc0 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
20dd0 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
20de0 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
20df0 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
20e00 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
20e10 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
20e20 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
20e30 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
20e40 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
20e50 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
20e60 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
20e70 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
20e80 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
20e90 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
20ea0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
20eb0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
20ec0 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
20ed0 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
20ee0 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a  minator bytes..*
20ef0 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69 73 20  *.** *pzTail is 
20f00 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
20f10 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 20   the first byte 
20f20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
20f30 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 53 51 4c  the.** first SQL
20f40 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
20f50 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
20f60 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65  nes only compile
20f70 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 73 74   the first.** st
20f80 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
20f90 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
20fa0 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
20fb0 77 68 61 74 20 72 65 6d 61 69 6e 73 0a 2a 2a 20  what remains.** 
20fc0 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
20fd0 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66  * *ppStmt is lef
20fe0 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
20ff0 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
21000 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
21010 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
21020 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
21030 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 49  ite3_step()].  I
21040 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
21050 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
21060 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
21070 20 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65   If the input te
21080 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
21090 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
210a0 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
210b0 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
210c0 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
210d0 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
210e0 2e 0a 2a 2a 20 7b 41 31 33 30 31 38 7d 20 54 68  ..** {A13018} Th
210f0 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
21100 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
21110 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
21120 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
21130 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
21140 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
21150 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
21160 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
21170 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  ith it..**.** On
21180 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54   success, [SQLIT
21190 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
211a0 64 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  d, otherwise an 
211b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
211c0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
211d0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
211e0 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
211f0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
21200 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
21210 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
21220 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
21230 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
21240 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
21250 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
21260 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
21270 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
21280 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
21290 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49  iscouraged..** I
212a0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
212b0 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
212c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
212d0 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
212e0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
212f0 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
21300 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
21310 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
21320 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
21330 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
21340 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
21350 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
21360 76 65 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79  ve a differently
21370 20 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a   in two ways:.**
21380 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
21390 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
213a0 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
213b0 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
213c0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
213d0 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
213e0 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
213f0 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
21400 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
21410 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
21420 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
21430 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
21440 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
21450 20 20 49 66 20 74 68 65 20 73 63 68 65 6d 61 20    If the schema 
21460 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a  has changed in.*
21470 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b  * a way that mak
21480 65 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  es the statement
21490 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64   no longer valid
214a0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
214b0 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a  )] will still.**
214c0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
214d0 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e  SCHEMA].  But un
214e0 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20  like the legacy 
214f0 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54  behavior, [SQLIT
21500 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20  E_SCHEMA] is.** 
21510 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f  now a fatal erro
21520 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  r.  Calling [sql
21530 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21540 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f  )] again will no
21550 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72  t make the.** er
21560 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f  ror go away.  No
21570 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33  te: use [sqlite3
21580 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69  _errmsg()] to fi
21590 6e 64 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f  nd the text.** o
215a0 66 20 74 68 65 20 70 61 72 73 69 6e 67 20 65 72  f the parsing er
215b0 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74 73  ror that results
215c0 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53   in an [SQLITE_S
215d0 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a  CHEMA] return..*
215e0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
215f0 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72  i>.** When an er
21600 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
21610 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
21620 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
21630 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
21640 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
21650 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
21660 20 63 6f 64 65 73 5d 2e 20 20 54 68 65 20 6c 65   codes].  The le
21670 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
21680 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  s that.** [sqlit
21690 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
216a0 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
216b0 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45  eneric [SQLITE_E
216c0 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
216d0 65 0a 2a 2a 20 61 6e 64 20 79 6f 75 20 77 6f 75  e.** and you wou
216e0 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
216f0 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
21700 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
21710 29 5d 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  )] in order.** t
21720 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
21730 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
21740 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68  he problem. With
21750 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
21760 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c  e.** interfaces,
21770 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
21780 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
21790 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
217a0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
217b0 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
217c0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
217d0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 31 7d  :.**.** {H13011}
217e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   The [sqlite3_pr
217f0 65 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 2e 2e  epare(db,zSql,..
21800 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  .)] and.**      
21810 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
21820 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  pare_v2(db,zSql,
21830 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73  ...)] interfaces
21840 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a   interpret the.*
21850 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20  *          text 
21860 69 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61  in their zSql pa
21870 72 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 38  rameter as UTF-8
21880 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 32 7d  ..**.** {H13012}
21890 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   The [sqlite3_pr
218a0 65 70 61 72 65 31 36 28 64 62 2c 7a 53 71 6c 2c  epare16(db,zSql,
218b0 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  ...)] and.**    
218c0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
218d0 72 65 70 61 72 65 31 36 5f 76 32 28 64 62 2c 7a  repare16_v2(db,z
218e0 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  Sql,...)] interf
218f0 61 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 74  aces interpret t
21900 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  he.**          t
21910 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71  ext in their zSq
21920 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 55  l parameter as U
21930 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
21940 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
21950 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 33 7d 20 49  **.** {H13013} I
21960 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
21970 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
21980 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a  _prepare_v2(db,z
21990 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a  Sql,nByte,...)].
219a0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
219b0 69 74 73 20 76 61 72 69 61 6e 74 73 20 69 73 20  its variants is 
219c0 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20  less than zero, 
219d0 74 68 65 20 53 51 4c 20 74 65 78 74 20 69 73 0a  the SQL text is.
219e0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 61 64  **          read
219f0 20 66 72 6f 6d 20 7a 53 71 6c 20 69 73 20 72 65   from zSql is re
21a00 61 64 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  ad up to the fir
21a10 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
21a20 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31  or..**.** {H1301
21a30 34 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20  4} If the nByte 
21a40 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
21a50 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21a60 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e  db,zSql,nByte,..
21a70 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
21a80 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
21a90 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
21aa0 2c 20 74 68 65 6e 20 61 74 20 6d 6f 73 74 20 6e  , then at most n
21ab0 42 79 74 65 73 20 62 79 74 65 73 20 6f 66 0a 2a  Bytes bytes of.*
21ac0 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 74  *          SQL t
21ad0 65 78 74 20 69 73 20 72 65 61 64 20 66 72 6f 6d  ext is read from
21ae0 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   zSql..**.** {H1
21af0 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c 69 74 65  3015} In [sqlite
21b00 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c  3_prepare_v2(db,
21b10 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69 6c 29  zSql,N,P,pzTail)
21b20 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
21b30 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ts.**          i
21b40 66 20 74 68 65 20 7a 53 71 6c 20 69 6e 70 75 74  f the zSql input
21b50 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6d   text contains m
21b60 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 53 51 4c  ore than one SQL
21b70 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20   statement.**   
21b80 20 20 20 20 20 20 20 61 6e 64 20 70 7a 54 61 69         and pzTai
21b90 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  l is not NULL, t
21ba0 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
21bb0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
21bc0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
21bd0 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20  first byte past 
21be0 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
21bf0 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
21c00 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a 20 20  nt in zSql..**  
21c10 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 57 68          <todo>Wh
21c20 61 74 20 64 6f 65 73 20 2a 70 7a 54 61 69 6c 20  at does *pzTail 
21c30 70 6f 69 6e 74 20 74 6f 20 69 66 20 74 68 65 72  point to if ther
21c40 65 20 69 73 20 6f 6e 65 20 73 74 61 74 65 6d 65  e is one stateme
21c50 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  nt?</todo>.**.**
21c60 20 7b 48 31 33 30 31 36 7d 20 41 20 73 75 63 63   {H13016} A succ
21c70 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
21c80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21c90 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70 70 53  v2(db,zSql,N,ppS
21ca0 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  tmt,...)].**    
21cb0 20 20 20 20 20 20 6f 72 20 6f 6e 65 20 6f 66 20        or one of 
21cc0 69 74 73 20 76 61 72 69 61 6e 74 73 20 77 72 69  its variants wri
21cd0 74 65 73 20 69 6e 74 6f 20 2a 70 70 53 74 6d 74  tes into *ppStmt
21ce0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
21cf0 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  new.**          
21d00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21d10 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69 6e 74 65  ent] or a pointe
21d20 72 20 74 6f 20 4e 55 4c 4c 20 69 66 20 7a 53 71  r to NULL if zSq
21d30 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20  l contains.**   
21d40 20 20 20 20 20 20 20 6e 6f 74 68 69 6e 67 20 6f         nothing o
21d50 74 68 65 72 20 74 68 61 6e 20 77 68 69 74 65 73  ther than whites
21d60 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  pace or comments
21d70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 39 7d  ..**.** {H13019}
21d80 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   The [sqlite3_pr
21d90 65 70 61 72 65 5f 76 32 28 29 5d 20 69 6e 74 65  epare_v2()] inte
21da0 72 66 61 63 65 20 61 6e 64 20 69 74 73 20 76 61  rface and its va
21db0 72 69 61 6e 74 73 20 72 65 74 75 72 6e 0a 2a 2a  riants return.**
21dc0 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
21dd0 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61 70 70 72  E_OK] or an appr
21de0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
21df0 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69 6c 75 72  ode] upon failur
21e00 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 32 31  e..**.** {H13021
21e10 7d 20 42 65 66 6f 72 65 20 5b 73 71 6c 69 74 65  } Before [sqlite
21e20 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71  3_prepare(db,zSq
21e30 6c 2c 6e 42 79 74 65 2c 70 70 53 74 6d 74 2c 70  l,nByte,ppStmt,p
21e40 7a 54 61 69 6c 29 5d 20 6f 72 20 69 74 73 0a 2a  zTail)] or its.*
21e50 2a 20 20 20 20 20 20 20 20 20 20 76 61 72 69 61  *          varia
21e60 6e 74 73 20 72 65 74 75 72 6e 73 20 61 6e 20 65  nts returns an e
21e70 72 72 6f 72 20 28 61 6e 79 20 76 61 6c 75 65 20  rror (any value 
21e80 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
21e90 54 45 5f 4f 4b 5d 29 2c 0a 2a 2a 20 20 20 20 20  TE_OK]),.**     
21ea0 20 20 20 20 20 74 68 65 79 20 66 69 72 73 74 20       they first 
21eb0 73 65 74 20 2a 70 70 53 74 6d 74 20 74 6f 20 4e  set *ppStmt to N
21ec0 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
21ed0 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
21ee0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
21ef0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
21f00 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
21f10 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
21f20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
21f30 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
21f40 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
21f50 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
21f60 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
21f70 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
21f80 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
21f90 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
21fa0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
21fb0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
21fc0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
21fd0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
21fe0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
21ff0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
22000 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
22010 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
22020 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
22030 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
22040 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
22050 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
22060 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
22070 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
22080 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
22090 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
220a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
220b0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
220c0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
220d0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
220e0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
220f0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
22100 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
22110 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
22120 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
22130 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
22140 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
22150 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
22160 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
22170 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
22180 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
22190 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
221a0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
221b0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
221c0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
221d0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
221e0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
221f0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
22200 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
22210 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
22220 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
22230 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
22240 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
22250 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
22260 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
22270 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
22280 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
22290 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
222a0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
222b0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
222c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
222d0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
222e0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
222f0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
22300 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
22310 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
22320 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
22330 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
22340 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
22350 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
22360 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
22370 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
22380 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
22390 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
223a0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
223b0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
223c0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
223d0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
223e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
223f0 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
22400 65 6d 65 6e 74 20 53 51 4c 20 7b 48 31 33 31 30  ement SQL {H1310
22410 30 7d 20 3c 48 31 33 30 30 30 3e 0a 2a 2a 0a 2a  0} <H13000>.**.*
22420 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
22430 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
22440 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64  retrieve a saved
22450 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69   copy of the ori
22460 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78  ginal.** SQL tex
22470 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
22480 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
22490 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20  tement] if that 
224a0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a  statement was.**
224b0 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
224c0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
224d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
224e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
224f0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
22500 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
22510 2a 2a 20 7b 48 31 33 31 30 31 7d 20 49 66 20 74  ** {H13101} If t
22520 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
22530 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64 20 61  tement] passed a
22540 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
22550 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
22560 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 77 61  qlite3_sql()] wa
22570 73 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  s compiled using
22580 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
22590 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
225a0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
225b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
225c0 5f 76 32 28 29 5d 2c 20 74 68 65 6e 20 5b 73 71  _v2()], then [sq
225d0 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 72 65 74  lite3_sql()] ret
225e0 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
225f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
22600 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
22610 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
22620 67 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  g a UTF-8 render
22630 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
22640 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  of the original 
22650 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
22660 2a 0a 2a 2a 20 7b 48 31 33 31 30 32 7d 20 49 66  *.** {H13102} If
22670 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
22680 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64  tatement] passed
22690 20 61 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   as the argument
226a0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
226b0 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20  [sqlite3_sql()] 
226c0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  was compiled usi
226d0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
226e0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
226f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
22700 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
22710 29 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  )], then [sqlite
22720 33 5f 73 71 6c 28 29 5d 20 72 65 74 75 72 6e 73  3_sql()] returns
22730 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
22740 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 33 7d 20  .**.** {H13103} 
22750 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72  The string retur
22760 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
22770 73 71 6c 28 53 29 5d 20 69 73 20 76 61 6c 69 64  sql(S)] is valid
22780 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a 20 20 20   until the.**   
22790 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
227a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73   statement] S is
227b0 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 5b   deleted using [
227c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
227d0 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  (S)]..*/.const c
227e0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
227f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
22800 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
22810 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61  PI3REF: Dynamica
22820 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
22830 4f 62 6a 65 63 74 20 7b 48 31 35 30 30 30 7d 20  Object {H15000} 
22840 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S20200>.** KEYW
22850 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
22860 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
22870 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
22880 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
22890 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
228a0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
228b0 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
228c0 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
228d0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
228e0 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
228f0 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
22900 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
22910 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
22920 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
22930 2e 20 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20  . Values stored 
22940 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
22950 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
22960 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
22970 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
22980 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
22990 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
229a0 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
229b0 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
229c0 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
229d0 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
229e0 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
229f0 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
22a00 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
22a10 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
22a20 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
22a30 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
22a40 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
22a50 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
22a60 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
22a70 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
22a80 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
22a90 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
22aa0 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
22ab0 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
22ac0 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
22ad0 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
22ae0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
22af0 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
22b00 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
22b10 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
22b20 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
22b30 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
22b40 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e   held.  A intern
22b50 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
22b60 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
22b70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
22b80 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
22b90 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
22ba0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
22bb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
22bc0 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
22bd0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
22be0 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
22bf0 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
22c00 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
22c10 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b  FE=0] and with [
22c20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
22c30 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20  fe()] returning 
22c40 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69  0).** or if SQLi
22c50 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65  te is run in one
22c60 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65   of reduced mute
22c70 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c  x modes .** [SQL
22c80 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
22c90 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c  ETHREAD] or [SQL
22ca0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
22cb0 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20  THREAD].** then 
22cc0 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74  there is no dist
22cd0 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
22ce0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
22cf0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
22d00 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
22d10 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20  ts and they can 
22d20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  be used intercha
22d30 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65  ngeably.  Howeve
22d40 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75  r,.** for maximu
22d50 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69  m code portabili
22d60 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ty it is recomme
22d70 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
22d80 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20  ations.** still 
22d90 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
22da0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 62 65 74  tion between bet
22db0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
22dc0 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
22dd0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
22de0 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65  objects even whe
22df0 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72  n not strictly r
22e00 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
22e10 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
22e20 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
22e30 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
22e40 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
22e50 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
22e60 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
22e70 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
22e80 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
22e90 74 65 63 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73  tected..** The s
22ea0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
22eb0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
22ec0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
22ed0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
22ee0 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
22ef0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
22f00 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
22f10 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
22f20 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
22f30 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
22f40 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
22f50 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
22f60 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
22f70 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
22f80 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
22f90 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
22fa0 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
22fb0 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
22fc0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
22fd0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
22fe0 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
22ff0 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
23000 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
23010 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
23020 6a 65 63 74 20 7b 48 31 36 30 30 31 7d 20 3c 53  ject {H16001} <S
23030 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
23040 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63   context in whic
23050 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  h an SQL functio
23060 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74  n executes is st
23070 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71  ored in an.** sq
23080 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
23090 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74 65 72  ject.  A pointer
230a0 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
230b0 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
230c0 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
230d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
230e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
230f0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
23100 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
23110 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
23120 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
23130 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
23140 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
23150 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
23160 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
23170 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
23180 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
23190 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
231a0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
231b0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
231c0 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
231d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
231e0 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
231f0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
23200 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
23210 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
23220 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
23230 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
23240 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
23250 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
23260 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
23270 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
23280 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
23290 6e 74 73 20 7b 48 31 33 35 30 30 7d 20 3c 53 37  nts {H13500} <S7
232a0 30 33 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0300>.** KEYWORD
232b0 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
232c0 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
232d0 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
232e0 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
232f0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
23300 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
23310 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
23320 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
23330 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c 20 73  .** In the SQL s
23340 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74 6f 20  trings input to 
23350 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23360 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76  _v2()] and its v
23370 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65  ariants,.** lite
23380 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c  rals may be repl
23390 61 63 65 64 20 62 79 20 61 20 70 61 72 61 6d 65  aced by a parame
233a0 74 65 72 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  ter in one of th
233b0 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a  ese forms:.**.**
233c0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
233d0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
233e0 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
233f0 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
23400 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
23410 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70  >.**.** In the p
23420 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73  arameter forms s
23430 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69  hown above NNN i
23440 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
23450 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56  eral,.** and VVV
23460 20 69 73 20 61 6e 20 61 6c 70 68 61 2d 6e 75 6d   is an alpha-num
23470 65 72 69 63 20 70 61 72 61 6d 65 74 65 72 20 6e  eric parameter n
23480 61 6d 65 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ame. The values 
23490 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
234a0 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
234b0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
234c0 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
234d0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
234e0 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
234f0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
23500 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
23510 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
23520 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
23530 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
23540 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
23550 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
23560 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
23570 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
23580 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
23590 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
235a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
235b0 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
235c0 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  iants..**.** The
235d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
235e0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
235f0 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
23600 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
23610 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51   The leftmost SQ
23620 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
23630 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
23640 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
23650 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
23660 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
23670 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
23680 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
23690 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
236a0 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
236b0 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
236c0 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
236d0 2a 20 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20  * The index for 
236e0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73  named parameters
236f0 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75   can be looked u
23700 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  p using the.** [
23710 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
23720 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20  ameter_index()] 
23730 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20  API if desired. 
23740 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f   The index.** fo
23750 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
23760 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
23770 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20   of NNN..** The 
23780 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
23790 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
237a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
237b0 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
237c0 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
237d0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
237e0 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
237f0 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  : 999)..**.** Th
23800 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
23810 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
23820 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
23830 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ameter..**.** In
23840 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
23850 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
23860 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
23870 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
23880 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
23890 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
238a0 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
238b0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
238c0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
238d0 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
238e0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
238f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
23900 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68  acters..** If th
23910 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
23920 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
23930 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
23940 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
23950 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
23960 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
23970 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
23980 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  or..**.** The fi
23990 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
239a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
239b0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
239c0 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
239d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
239e0 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
239f0 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
23a00 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
23a10 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
23a20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
23a30 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
23a40 74 2e 20 49 66 20 74 68 65 20 66 69 66 74 68 20  t. If the fifth 
23a50 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
23a60 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
23a70 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
23a80 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
23a90 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
23aa0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
23ab0 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
23ac0 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
23ad0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
23ae0 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66   be freed..** If
23af0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
23b00 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
23b10 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
23b20 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
23b30 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
23b40 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
23b50 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
23b60 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
23b70 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
23b80 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
23b90 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  returns..**.** T
23ba0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
23bb0 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
23bc0 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
23bd0 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
23be0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
23bf0 74 68 20 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65  th zeroes.  A ze
23c00 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
23c10 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
23c20 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
23c30 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
23c40 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65   its size) while
23c50 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
23c60 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
23c70 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
23c80 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
23c90 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
23ca0 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
23cb0 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
23cc0 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20  ritten using.** 
23cd0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
23ce0 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
23cf0 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69   BLOB I/O] routi
23d00 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69  nes..** A negati
23d10 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
23d20 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
23d30 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
23d40 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54  th BLOB..**.** T
23d50 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
23d60 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  *() routines mus
23d70 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65  t be called afte
23d80 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
23d90 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64  epare_v2()] (and
23da0 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f   its variants) o
23db0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
23dc0 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72  ()] and.** befor
23dd0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
23de0 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20  )]..** Bindings 
23df0 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
23e00 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
23e10 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
23e20 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72  ..** Unbound par
23e30 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
23e40 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
23e50 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
23e60 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
23e70 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
23e80 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20  ess or an error 
23e90 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68  code if.** anyth
23ea0 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20  ing goes wrong. 
23eb0 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20   [SQLITE_RANGE] 
23ec0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
23ed0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
23ee0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
23ef0 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f  range.  [SQLITE_
23f00 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
23f10 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
23f20 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45  ails..** [SQLITE
23f30 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62  _MISUSE] might b
23f40 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  e returned if th
23f50 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
23f60 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20   called on a.** 
23f70 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
23f80 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e  that is the wron
23f90 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 68  g state or which
23fa0 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65   has already bee
23fb0 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20  n finalized..** 
23fc0 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73  Detection of mis
23fd0 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c  use is unreliabl
23fe0 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  e.  Applications
23ff0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65   should not depe
24000 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f  nd.** on SQLITE_
24010 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20  MISUSE returns. 
24020 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69   SQLITE_MISUSE i
24030 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e  s intended to in
24040 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f  dicate a.** a lo
24050 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65  gic error in the
24060 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46   application.  F
24070 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
24080 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
24090 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72 20 74  * panic rather t
240a0 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54  han return SQLIT
240b0 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20  E_MISUSE..**.** 
240c0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
240d0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
240e0 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
240f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
24100 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
24110 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
24120 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
24130 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  x()]..**.** INVA
24140 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
24150 31 33 35 30 36 7d 20 54 68 65 20 5b 53 51 4c 20  13506} The [SQL 
24160 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
24170 65 72 5d 20 72 65 63 6f 67 6e 69 7a 65 73 20 74  er] recognizes t
24180 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20 66 6f 72  okens of the for
24190 6d 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 22  ms.**          "
241a0 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24 56 56  ?", "?NNN", "$VV
241b0 56 22 2c 20 22 3a 56 56 56 22 2c 20 61 6e 64 20  V", ":VVV", and 
241c0 22 40 56 56 56 22 20 61 73 20 53 51 4c 20 70 61  "@VVV" as SQL pa
241d0 72 61 6d 65 74 65 72 73 2c 0a 2a 2a 20 20 20 20  rameters,.**    
241e0 20 20 20 20 20 20 77 68 65 72 65 20 4e 4e 4e 20        where NNN 
241f0 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20  is any sequence 
24200 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 64  of one or more d
24210 69 67 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  igits.**        
24220 20 20 61 6e 64 20 77 68 65 72 65 20 56 56 56 20    and where VVV 
24230 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20  is any sequence 
24240 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 61  of one or more a
24250 6c 70 68 61 6e 75 6d 65 72 69 63 0a 2a 2a 20 20  lphanumeric.**  
24260 20 20 20 20 20 20 20 20 63 68 61 72 61 63 74 65          characte
24270 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70 74 69 6f  rs or "::" optio
24280 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62  nally followed b
24290 79 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  y a string conta
242a0 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  ining.**        
242b0 20 20 6e 6f 20 73 70 61 63 65 73 20 61 6e 64 20    no spaces and 
242c0 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e  contained within
242d0 20 70 61 72 65 6e 74 68 65 73 65 73 2e 0a 2a 2a   parentheses..**
242e0 0a 2a 2a 20 7b 48 31 33 35 30 39 7d 20 54 68 65  .** {H13509} The
242f0 20 69 6e 69 74 69 61 6c 20 76 61 6c 75 65 20 6f   initial value o
24300 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
24310 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  er is NULL..**.*
24320 2a 20 7b 48 31 33 35 31 32 7d 20 54 68 65 20 69  * {H13512} The i
24330 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 22 20 53  ndex of an "?" S
24340 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
24350 6f 6e 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20  one larger than 
24360 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
24370 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66  largest index of
24380 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
24390 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f 72 20 31  o the left, or 1
243a0 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
243b0 74 68 65 20 22 3f 22 20 69 73 20 74 68 65 20 6c  the "?" is the l
243c0 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
243d0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  meter..**.** {H1
243e0 33 35 31 35 7d 20 54 68 65 20 69 6e 64 65 78 20  3515} The index 
243f0 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c  of an "?NNN" SQL
24400 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
24410 65 20 69 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a  e integer NNN..*
24420 2a 0a 2a 2a 20 7b 48 31 33 35 31 38 7d 20 54 68  *.** {H13518} Th
24430 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3a  e index of an ":
24440 56 56 56 22 2c 20 22 24 56 56 56 22 2c 20 6f 72  VVV", "$VVV", or
24450 20 22 40 56 56 56 22 20 53 51 4c 20 70 61 72 61   "@VVV" SQL para
24460 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20  meter is.**     
24470 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 73       the same as
24480 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 6c 65   the index of le
24490 66 74 6d 6f 73 74 20 6f 63 63 75 72 72 65 6e 63  ftmost occurrenc
244a0 65 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  es of the same.*
244b0 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
244c0 65 74 65 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72  eter, or one mor
244d0 65 20 74 68 61 6e 20 74 68 65 20 6c 61 72 67 65  e than the large
244e0 73 74 20 69 6e 64 65 78 20 6f 76 65 72 20 61 6c  st index over al
244f0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  l.**          pa
24500 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
24510 6c 65 66 74 20 69 66 20 74 68 69 73 20 69 73 20  left if this is 
24520 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
24530 65 6e 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  ence.**         
24540 20 6f 66 20 74 68 69 73 20 70 61 72 61 6d 65 74   of this paramet
24550 65 72 2c 20 6f 72 20 31 20 69 66 20 74 68 69 73  er, or 1 if this
24560 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74   is the leftmost
24570 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
24580 2a 20 7b 48 31 33 35 32 31 7d 20 54 68 65 20 5b  * {H13521} The [
24590 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
245a0 6d 70 69 6c 65 72 5d 20 66 61 69 6c 73 20 77 69  mpiler] fails wi
245b0 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 52 41  th an [SQLITE_RA
245c0 4e 47 45 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  NGE].**         
245d0 20 65 72 72 6f 72 20 69 66 20 74 68 65 20 69 6e   error if the in
245e0 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
245f0 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
24600 74 68 61 6e 20 31 0a 2a 2a 20 20 20 20 20 20 20  than 1.**       
24610 20 20 20 6f 72 20 67 72 65 61 74 65 72 20 74 68     or greater th
24620 61 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  an the compile-t
24630 69 6d 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56  ime SQLITE_MAX_V
24640 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 0a 2a  ARIABLE_NUMBER.*
24650 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
24660 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  eter..**.** {H13
24670 35 32 34 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73  524} Calls to [s
24680 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
24690 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28   | sqlite3_bind(
246a0 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  S,N,V,...)].**  
246b0 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 61 74          associat
246c0 65 20 74 68 65 20 76 61 6c 75 65 20 56 20 77 69  e the value V wi
246d0 74 68 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d  th all SQL param
246e0 65 74 65 72 73 20 68 61 76 69 6e 67 20 61 6e 0a  eters having an.
246f0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 64 65  **          inde
24700 78 20 6f 66 20 4e 20 69 6e 20 74 68 65 20 5b 70  x of N in the [p
24710 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24720 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  t] S..**.** {H13
24730 35 32 37 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73  527} Calls to [s
24740 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
24750 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28   | sqlite3_bind(
24760 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  S,N,...)].**    
24770 20 20 20 20 20 20 6f 76 65 72 72 69 64 65 20 70        override p
24780 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 20  rior calls with 
24790 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20  the same values 
247a0 6f 66 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a  of S and N..**.*
247b0 2a 20 7b 48 31 33 35 33 30 7d 20 42 69 6e 64 69  * {H13530} Bindi
247c0 6e 67 73 20 65 73 74 61 62 6c 69 73 68 65 64 20  ngs established 
247d0 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  by [sqlite3_bind
247e0 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f  _text | sqlite3_
247f0 62 69 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20  bind(S,...)].** 
24800 20 20 20 20 20 20 20 20 20 70 65 72 73 69 73 74           persist
24810 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f   across calls to
24820 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
24830 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  S)]..**.** {H135
24840 33 33 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  33} In calls to 
24850 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
24860 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a  ob(S,N,V,L,D)],.
24870 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
24880 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53  ite3_bind_text(S
24890 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a  ,N,V,L,D)], or.*
248a0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
248b0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
248c0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69  S,N,V,L,D)] SQLi
248d0 74 65 20 62 69 6e 64 73 20 74 68 65 20 66 69 72  te binds the fir
248e0 73 74 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  st L.**         
248f0 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c   bytes of the BL
24900 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 70 6f 69  OB or string poi
24910 6e 74 65 64 20 74 6f 20 62 79 20 56 2c 20 77 68  nted to by V, wh
24920 65 6e 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  en L.**         
24930 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
24940 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 36 7d  ..**.** {H13536}
24950 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
24960 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
24970 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a  S,N,V,L,D)] or.*
24980 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
24990 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
249a0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69  S,N,V,L,D)] SQLi
249b0 74 65 20 62 69 6e 64 73 20 63 68 61 72 61 63 74  te binds charact
249c0 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ers.**          
249d0 66 72 6f 6d 20 56 20 74 68 72 6f 75 67 68 20 74  from V through t
249e0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
249f0 61 72 61 63 74 65 72 20 77 68 65 6e 20 4c 20 69  aracter when L i
24a00 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  s negative..**.*
24a10 2a 20 7b 48 31 33 35 33 39 7d 20 49 6e 20 63 61  * {H13539} In ca
24a20 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
24a30 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
24a40 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
24a50 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
24a60 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
24a70 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
24a80 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
24a90 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
24aa0 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65  )] when D is the
24ab0 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20   special.**     
24ac0 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53       constant [S
24ad0 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 53  QLITE_STATIC], S
24ae0 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
24af0 61 74 20 74 68 65 20 76 61 6c 75 65 20 56 0a 2a  at the value V.*
24b00 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 68 65  *          is he
24b10 6c 64 20 69 6e 20 73 74 61 74 69 63 20 75 6e 6d  ld in static unm
24b20 61 6e 61 67 65 64 20 73 70 61 63 65 20 74 68 61  anaged space tha
24b30 74 20 77 69 6c 6c 20 6e 6f 74 20 63 68 61 6e 67  t will not chang
24b40 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 75  e.**          du
24b50 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
24b60 65 20 6f 66 20 74 68 65 20 62 69 6e 64 69 6e 67  e of the binding
24b70 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 32 7d  ..**.** {H13542}
24b80 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
24b90 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
24ba0 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
24bb0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
24bc0 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
24bd0 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
24be0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
24bf0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
24c00 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20  ,V,L,D)] when D 
24c10 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a  is the special.*
24c20 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  *          const
24c30 61 6e 74 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  ant [SQLITE_TRAN
24c40 53 49 45 4e 54 5d 2c 20 74 68 65 20 72 6f 75 74  SIENT], the rout
24c50 69 6e 65 20 6d 61 6b 65 73 20 61 0a 2a 2a 20 20  ine makes a.**  
24c60 20 20 20 20 20 20 20 20 70 72 69 76 61 74 65 20          private 
24c70 63 6f 70 79 20 6f 66 20 74 68 65 20 76 61 6c 75  copy of the valu
24c80 65 20 56 20 62 65 66 6f 72 65 20 69 74 20 72 65  e V before it re
24c90 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  turns..**.** {H1
24ca0 33 35 34 35 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3545} In calls t
24cb0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
24cc0 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  blob(S,N,V,L,D)]
24cd0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
24ce0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
24cf0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72  (S,N,V,L,D)], or
24d00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
24d10 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
24d20 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68  6(S,N,V,L,D)] wh
24d30 65 6e 20 44 20 69 73 20 61 20 70 6f 69 6e 74 65  en D is a pointe
24d40 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
24d50 20 61 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c   a function, SQL
24d60 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 61 74  ite invokes that
24d70 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 64 65 73   function to des
24d80 74 72 6f 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  troy the.**     
24d90 20 20 20 20 20 76 61 6c 75 65 20 56 20 61 66 74       value V aft
24da0 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
24db0 65 64 20 75 73 69 6e 67 20 74 68 65 20 76 61 6c  ed using the val
24dc0 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ue V..**.** {H13
24dd0 35 34 38 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  548} In calls to
24de0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a   [sqlite3_bind_z
24df0 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 29  eroblob(S,N,V,L)
24e00 5d 20 74 68 65 20 76 61 6c 75 65 20 62 6f 75 6e  ] the value boun
24e10 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  d.**          is
24e20 20 61 20 42 4c 4f 42 20 6f 66 20 4c 20 62 79 74   a BLOB of L byt
24e30 65 73 2c 20 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  es, or a zero-le
24e40 6e 67 74 68 20 42 4c 4f 42 20 69 66 20 4c 20 69  ngth BLOB if L i
24e50 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  s negative..**.*
24e60 2a 20 7b 48 31 33 35 35 31 7d 20 49 6e 20 63 61  * {H13551} In ca
24e70 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
24e80 62 69 6e 64 5f 76 61 6c 75 65 28 53 2c 4e 2c 56  bind_value(S,N,V
24e90 29 5d 20 74 68 65 20 56 20 61 72 67 75 6d 65 6e  )] the V argumen
24ea0 74 20 6d 61 79 0a 2a 2a 20 20 20 20 20 20 20 20  t may.**        
24eb0 20 20 62 65 20 65 69 74 68 65 72 20 61 20 5b 70    be either a [p
24ec0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
24ed0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6f  _value] object o
24ee0 72 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  r an.**         
24ef0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
24f00 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
24f10 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ect..*/.int sqli
24f20 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
24f30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
24f40 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
24f50 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
24f60 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
24f70 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
24f80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24f90 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
24fa0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
24fb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24fc0 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
24fd0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
24fe0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
24ff0 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
25000 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
25010 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
25020 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
25030 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
25040 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
25050 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
25060 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
25070 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
25080 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
25090 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
250a0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
250b0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
250c0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
250d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
250e0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
250f0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
25100 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
25110 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
25120 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
25130 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
25140 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
25150 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
25160 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
25170 20 7b 48 31 33 36 30 30 7d 20 3c 53 37 30 33 30   {H13600} <S7030
25180 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
25190 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
251a0 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
251b0 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
251c0 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
251d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
251e0 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
251f0 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
25200 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
25210 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
25220 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
25230 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
25240 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
25250 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
25260 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
25270 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
25280 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
25290 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
252a0 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
252b0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61  * This routine a
252c0 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  ctually returns 
252d0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
252e0 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d   largest (rightm
252f0 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ost).** paramete
25300 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73  r. For all forms
25310 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68   except ?NNN, th
25320 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f  is will correspo
25330 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d  nd to the.** num
25340 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61  ber of unique pa
25350 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61  rameters.  If pa
25360 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
25370 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c 0a 2a  ?NNN are used,.*
25380 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
25390 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
253a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
253b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
253c0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
253d0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
253e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
253f0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
25400 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
25410 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
25420 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
25430 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 30  TS:.**.** {H1360
25440 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
25450 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
25460 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66 61  ount(S)] interfa
25470 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  ce returns.**   
25480 20 20 20 20 20 20 20 74 68 65 20 6c 61 72 67 65         the large
25490 73 74 20 69 6e 64 65 78 20 6f 66 20 61 6c 6c 20  st index of all 
254a0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 69  SQL parameters i
254b0 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
254c0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
254d0 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69  ement] S, or 0 i
254e0 66 20 53 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  f S contains no 
254f0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  SQL parameters..
25500 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
25510 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
25520 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
25530 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
25540 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
25550 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20 7b 48  ost Parameter {H
25560 31 33 36 32 30 7d 20 3c 53 37 30 33 30 30 3e 0a  13620} <S70300>.
25570 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
25580 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
25590 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65  nter to the name
255a0 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20   of the n-th.** 
255b0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
255c0 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
255d0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51  tatement]..** SQ
255e0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
255f0 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
25600 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
25610 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
25620 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
25630 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
25640 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
25650 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
25660 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
25670 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
25680 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
25690 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
256a0 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
256b0 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
256c0 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
256d0 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73  e..** Parameters
256e0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
256f0 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
25700 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
25710 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
25720 20 61 72 65 20 61 6c 73 6f 20 72 65 66 65 72 72   are also referr
25730 65 64 20 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d  ed to as "anonym
25740 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
25750 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
25760 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
25770 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
25780 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
25790 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69  If the value n i
257a0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
257b0 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61  r if the n-th pa
257c0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
257d0 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
257e0 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
257f0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
25800 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
25810 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
25820 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
25830 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
25840 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
25850 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
25860 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
25870 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
25880 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
25890 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
258a0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
258b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
258c0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
258d0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
258e0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
258f0 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
25900 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
25910 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
25920 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
25930 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 32 31 7d  :.**.** {H13621}
25940 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   The [sqlite3_bi
25950 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
25960 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
25970 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
25980 20 20 20 20 20 20 61 20 55 54 46 2d 38 20 72 65        a UTF-8 re
25990 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 6e  ndering of the n
259a0 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 70  ame of the SQL p
259b0 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 20  arameter in.**  
259c0 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65          the [pre
259d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
259e0 20 53 20 68 61 76 69 6e 67 20 69 6e 64 65 78 20   S having index 
259f0 4e 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  N, or.**        
25a00 20 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20    NULL if there 
25a10 69 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65  is no SQL parame
25a20 74 65 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e  ter with index N
25a30 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 20 20   or if the.**   
25a40 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
25a50 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20 69 73   with index N is
25a60 20 61 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20 70 61   an anonymous pa
25a70 72 61 6d 65 74 65 72 20 22 3f 22 2e 0a 2a 2f 0a  rameter "?"..*/.
25a80 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
25a90 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
25aa0 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
25ab0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
25ac0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
25ad0 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
25ae0 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
25af0 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d 20 3c 53  Name {H13640} <S
25b00 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74  70300>.**.** Ret
25b10 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
25b20 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
25b30 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
25b40 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20  .  The.** index 
25b50 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
25b60 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
25b70 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
25b80 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
25b90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
25ba0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
25bb0 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20  ()].  A zero.** 
25bc0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
25bd0 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
25be0 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
25bf0 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
25c00 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
25c10 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
25c20 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
25c30 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
25c40 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
25c50 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
25c60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
25c70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
25c80 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
25c90 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
25ca0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
25cb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
25cc0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
25cd0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
25ce0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
25cf0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
25d00 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
25d10 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 34 31 7d 20  .**.** {H13641} 
25d20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  The [sqlite3_bin
25d30 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
25d40 78 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  x(S,N)] interfac
25d50 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
25d60 20 20 20 20 20 20 74 68 65 20 69 6e 64 65 78 20        the index 
25d70 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  of SQL parameter
25d80 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
25d90 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
25da0 20 20 20 20 20 20 20 20 20 53 20 77 68 6f 73 65           S whose
25db0 20 6e 61 6d 65 20 6d 61 74 63 68 65 73 20 74 68   name matches th
25dc0 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 4e  e UTF-8 string N
25dd0 2c 20 6f 72 20 30 20 69 66 20 74 68 65 72 65 20  , or 0 if there 
25de0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  is.**          n
25df0 6f 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20  o match..*/.int 
25e00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
25e10 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
25e20 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
25e30 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
25e40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25e50 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
25e60 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
25e70 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33  d Statement {H13
25e80 36 36 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  660} <S70300>.**
25e90 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f 20  .** Contrary to 
25ea0 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
25eb0 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
25ec0 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
25ed0 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
25ee0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
25ef0 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
25f00 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
25f10 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 55 73 65 20  tement]..** Use 
25f20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
25f30 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
25f40 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
25f50 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  L..**.** INVARIA
25f60 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36  NTS:.**.** {H136
25f70 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  61} The [sqlite3
25f80 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
25f90 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
25fa0 73 65 74 73 20 61 6c 6c 20 53 51 4c 0a 2a 2a 20  sets all SQL.** 
25fb0 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74           paramet
25fc0 65 72 20 62 69 6e 64 69 6e 67 73 20 69 6e 20 74  er bindings in t
25fd0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
25fe0 74 65 6d 65 6e 74 5d 20 53 20 62 61 63 6b 20 74  tement] S back t
25ff0 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
26000 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
26010 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
26020 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
26030 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
26040 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
26050 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37 31 30  sult Set {H13710
26060 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10700>.**.**
26070 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62   Return the numb
26080 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
26090 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
260a0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
260b0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
260c0 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f  tement]. This ro
260d0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
260e0 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53  if pStmt is an S
260f0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
26100 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
26110 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65  turn data (for e
26120 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
26130 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  E])..**.** INVAR
26140 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
26150 33 37 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3711} The [sqlit
26160 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
26170 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
26180 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
26190 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
261a0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
261b0 65 73 75 6c 74 20 73 65 74 20 67 65 6e 65 72 61  esult set genera
261c0 74 65 64 20 62 79 20 74 68 65 20 5b 70 72 65 70  ted by the [prep
261d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
261e0 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  S,.**          o
261f0 72 20 30 20 69 66 20 53 20 64 6f 65 73 20 6e 6f  r 0 if S does no
26200 74 20 67 65 6e 65 72 61 74 65 20 61 20 72 65 73  t generate a res
26210 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20  ult set..*/.int 
26220 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
26230 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
26240 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
26250 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
26260 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
26270 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37 32 30  sult Set {H13720
26280 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10700>.**.**
26290 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
262a0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
262b0 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
262c0 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
262d0 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
262e0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
262f0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54  T] statement.  T
26300 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
26310 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
26320 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
26330 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
26340 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
26350 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
26360 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26370 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
26380 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
26390 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
263a0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
263b0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
263c0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
263d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
263e0 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
263f0 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
26400 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 54 68  T] statement. Th
26410 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
26420 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
26430 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65  umn number.  The
26440 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
26450 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
26460 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64  .** The returned
26470 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
26480 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
26490 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61  ither the [prepa
264a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
264b0 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  * is destroyed b
264c0 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
264d0 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
264e0 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
264f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
26500 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
26510 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
26520 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
26530 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49   column..**.** I
26540 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
26550 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
26560 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
26570 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
26580 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
26590 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
265a0 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
265b0 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
265c0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
265d0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
265e0 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
265f0 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
26600 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
26610 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
26620 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
26630 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
26640 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
26650 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
26660 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
26670 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
26680 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
26690 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
266a0 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
266b0 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
266c0 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
266d0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
266e0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 31  S:.**.** {H13721
266f0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
26700 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
26710 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
26720 5f 6e 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20  _name(S,N)].**  
26730 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
26740 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61  e returns the na
26750 6d 65 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f  me of the Nth co
26760 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73  lumn (where 0 is
26770 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
26780 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
26790 29 20 66 6f 72 20 74 68 65 20 72 65 73 75 6c 74  ) for the result
267a0 20 73 65 74 20 6f 66 20 74 68 65 0a 2a 2a 20 20   set of the.**  
267b0 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
267c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61  d statement] S a
267d0 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
267e0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
267f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 33 7d  ..**.** {H13723}
26800 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
26810 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
26820 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
26830 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20  name16(S,N)].** 
26840 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
26850 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
26860 61 6d 65 20 6f 66 20 74 68 65 20 4e 74 68 20 63  ame of the Nth c
26870 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69  olumn (where 0 i
26880 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
26890 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
268a0 6e 29 20 66 6f 72 20 74 68 65 20 72 65 73 75 6c  n) for the resul
268b0 74 20 73 65 74 20 6f 66 20 74 68 65 0a 2a 2a 20  t set of the.** 
268c0 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
268d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
268e0 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  as a zero-termin
268f0 61 74 65 64 20 55 54 46 2d 31 36 20 73 74 72 69  ated UTF-16 stri
26900 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ng.**          i
26910 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
26920 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  e order..**.** {
26930 48 31 33 37 32 34 7d 20 54 68 65 20 5b 73 71 6c  H13724} The [sql
26940 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
26950 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
26960 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
26970 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
26980 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20  terfaces return 
26990 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
269a0 66 20 74 68 65 79 20 61 72 65 20 75 6e 61 62 6c  f they are unabl
269b0 65 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  e to.**         
269c0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
269d0 20 74 6f 20 68 6f 6c 64 20 74 68 65 69 72 20 6e   to hold their n
269e0 6f 72 6d 61 6c 20 72 65 74 75 72 6e 20 73 74 72  ormal return str
269f0 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ings..**.** {H13
26a00 37 32 35 7d 20 49 66 20 74 68 65 20 4e 20 70 61  725} If the N pa
26a10 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
26a20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
26a30 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  S,N)] or.**     
26a40 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
26a50 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  lumn_name16(S,N)
26a60 5d 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  ] is out of rang
26a70 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20  e, then the.**  
26a80 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
26a90 65 73 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c  es return a NULL
26aa0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
26ab0 7b 48 31 33 37 32 36 7d 20 54 68 65 20 73 74 72  {H13726} The str
26ac0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
26ad0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
26ae0 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 61 6e 64 0a  _name(S,N)] and.
26af0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
26b00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
26b10 31 36 28 53 2c 4e 29 5d 20 61 72 65 20 76 61 6c  16(S,N)] are val
26b20 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  id until the nex
26b30 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  t.**          ca
26b40 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 72 6f 75  ll to either rou
26b50 74 69 6e 65 20 77 69 74 68 20 74 68 65 20 73 61  tine with the sa
26b60 6d 65 20 53 20 61 6e 64 20 4e 20 70 61 72 61 6d  me S and N param
26b70 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  eters.**        
26b80 20 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69    or until [sqli
26b90 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d  te3_finalize(S)]
26ba0 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a   is called..**.*
26bb0 2a 20 7b 48 31 33 37 32 37 7d 20 57 68 65 6e 20  * {H13727} When 
26bc0 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
26bd0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
26be0 61 74 65 6d 65 6e 74 20 63 6f 6e 74 61 69 6e 73  atement contains
26bf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20  .**          an 
26c00 41 53 20 63 6c 61 75 73 65 2c 20 74 68 65 20 6e  AS clause, the n
26c10 61 6d 65 20 6f 66 20 74 68 61 74 20 63 6f 6c 75  ame of that colu
26c20 6d 6e 20 69 73 20 74 68 65 20 69 64 65 6e 74 69  mn is the identi
26c30 66 69 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  fier.**         
26c40 20 74 6f 20 74 68 65 20 72 69 67 68 74 20 6f 66   to the right of
26c50 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64 2e   the AS keyword.
26c60 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
26c70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
26c80 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
26c90 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
26ca0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
26cb0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
26cc0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
26cd0 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
26ce0 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
26cf0 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
26d00 65 73 75 6c 74 20 7b 48 31 33 37 34 30 7d 20 3c  esult {H13740} <
26d10 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S10700>.**.** Th
26d20 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
26d30 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
26d40 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63  determine what c
26d50 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a  olumn of what.**
26d60 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20   table in which 
26d70 64 61 74 61 62 61 73 65 20 61 20 72 65 73 75 6c  database a resul
26d80 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
26d90 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20  statement comes 
26da0 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d  from..** The nam
26db0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
26dc0 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
26dd0 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
26de0 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
26df0 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
26e00 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65  -16 string.  The
26e10 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
26e20 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
26e30 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
26e40 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
26e50 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
26e60 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
26e70 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
26e80 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
26e90 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
26ea0 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65  ..** The returne
26eb0 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
26ec0 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
26ed0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26ee0 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
26ef0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
26f00 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
26f10 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
26f20 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
26f30 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
26f40 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
26f50 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  ncoding..**.** T
26f60 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
26f70 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
26f80 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
26f90 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
26fa0 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
26fb0 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
26fc0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
26fd0 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f  ent to the follo
26fe0 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20  wing calls is a 
26ff0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27000 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66  ent]..** These f
27010 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
27020 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
27030 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  t the Nth column
27040 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
27050 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
27060 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
27070 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
27080 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  gument..**.** If
27090 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
270a0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
270b0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
270c0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a  expression or.**
270d0 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
270e0 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
270f0 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
27100 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
27110 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e   return.** NULL.
27120 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20    These routine 
27130 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
27140 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
27150 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
27160 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
27170 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
27180 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
27190 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
271a0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 0a  database, table.
271b0 2a 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68  ** and column th
271c0 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
271d0 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
271e0 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
271f0 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68   As with all oth
27200 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
27210 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64 20  those postfixed 
27220 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
27230 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
27240 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65 20  ed strings, the 
27250 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
27260 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45  return UTF-8. {E
27270 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ND}.**.** These 
27280 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
27290 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
272a0 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
272b0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
272c0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
272d0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
272e0 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
272f0 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a  ymbol defined..*
27300 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 0a 2a 2a  *.** {A13751}.**
27310 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
27320 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
27330 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
27340 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
27350 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
27360 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27370 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
27380 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
27390 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
273a0 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
273b0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
273c0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 31  S:.**.** {H13741
273d0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
273e0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
273f0 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ame(S,N)] interf
27400 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
27410 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
27420 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  he UTF-8 zero-te
27430 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
27440 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
27450 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  om which the.** 
27460 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73           Nth res
27470 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ult column of th
27480 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
27490 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72  ement] S is extr
274a0 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20  acted,.**       
274b0 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68     or NULL if th
274c0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
274d0 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65  S is a general e
274e0 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20  xpression.**    
274f0 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62        or if unab
27500 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
27510 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74  emory to store t
27520 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b  he name..**.** {
27530 48 31 33 37 34 32 7d 20 54 68 65 20 5b 73 71 6c  H13742} The [sql
27540 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
27550 62 61 73 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  base_name16(S,N)
27560 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
27570 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
27580 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31         the UTF-1
27590 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
275a0 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  der zero-termina
275b0 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
275c0 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20  database.**     
275d0 20 20 20 20 20 66 72 6f 6d 20 77 68 69 63 68 20       from which 
275e0 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
275f0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72  olumn of the [pr
27600 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27610 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ] S is.**       
27620 20 20 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72     extracted, or
27630 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
27640 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
27650 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73  a general expres
27660 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  sion.**         
27670 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
27680 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
27690 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61   to store the na
276a0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34  me..**.** {H1374
276b0 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
276c0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
276d0 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
276e0 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
276f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
27700 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
27710 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
27720 68 65 20 74 61 62 6c 65 20 66 72 6f 6d 20 77 68  he table from wh
27730 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ich the.**      
27740 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63      Nth result c
27750 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72  olumn of the [pr
27760 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27770 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64  ] S is extracted
27780 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
27790 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
277a0 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
277b0 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73  a general expres
277c0 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  sion.**         
277d0 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
277e0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
277f0 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61   to store the na
27800 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34  me..**.** {H1374
27810 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
27820 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
27830 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  e16(S,N)] interf
27840 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
27850 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
27860 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  he UTF-16 native
27870 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f   byte order zero
27880 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65  -terminated name
27890 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
278a0 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 77            from w
278b0 68 69 63 68 20 74 68 65 20 4e 74 68 20 72 65 73  hich the Nth res
278c0 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ult column of th
278d0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
278e0 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a 20 20  ement] S is.**  
278f0 20 20 20 20 20 20 20 20 65 78 74 72 61 63 74 65          extracte
27900 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
27910 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
27920 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65  S is a general e
27930 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20  xpression.**    
27940 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62        or if unab
27950 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
27960 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74  emory to store t
27970 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b  he name..**.** {
27980 48 31 33 37 34 35 7d 20 54 68 65 20 5b 73 71 6c  H13745} The [sql
27990 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
279a0 69 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e  in_name(S,N)] in
279b0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
279c0 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
279d0 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72     the UTF-8 zer
279e0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
279f0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
27a00 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68  olumn from which
27a10 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
27a20 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
27a30 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61  mn of the [prepa
27a40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
27a50 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a   is extracted,.*
27a60 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55  *          or NU
27a70 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f  LL if the Nth co
27a80 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67  lumn of S is a g
27a90 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
27aa0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
27ab0 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   if unable to al
27ac0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
27ad0 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
27ae0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 36 7d 20  .**.** {H13746} 
27af0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
27b00 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
27b10 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  6(S,N)] interfac
27b20 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
27b30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
27b40 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
27b50 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74  yte order zero-t
27b60 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
27b70 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20  f the table.**  
27b80 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 66          column f
27b90 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74  rom which the Nt
27ba0 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
27bb0 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
27bc0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
27bd0 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74  tement] S is ext
27be0 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20  racted, or NULL 
27bf0 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
27c00 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  n.**          of
27c10 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20   S is a general 
27c20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66  expression or if
27c30 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
27c40 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20  ate memory.**   
27c50 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20         to store 
27c60 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  the name..**.** 
27c70 7b 48 31 33 37 34 38 7d 20 54 68 65 20 72 65 74  {H13748} The ret
27c80 75 72 6e 20 76 61 6c 75 65 73 20 66 72 6f 6d 0a  urn values from.
27c90 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
27ca0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
27cb0 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
27cc0 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
27cd0 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20  rfaces].**      
27ce0 20 20 20 20 61 72 65 20 76 61 6c 69 64 20 66 6f      are valid fo
27cf0 72 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  r the lifetime o
27d00 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
27d10 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20  statement].**   
27d20 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c 20         or until 
27d30 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
27d40 63 68 61 6e 67 65 64 20 62 79 20 61 6e 6f 74 68  changed by anoth
27d50 65 72 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20  er metadata.**  
27d60 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
27d70 65 20 63 61 6c 6c 20 66 6f 72 20 74 68 65 20 73  e call for the s
27d80 61 6d 65 20 70 72 65 70 61 72 65 64 20 73 74 61  ame prepared sta
27d90 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
27da0 6e 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54  n..**.** ASSUMPT
27db0 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 33  IONS:.**.** {A13
27dc0 37 35 31 7d 20 49 66 20 74 77 6f 20 6f 72 20 6d  751} If two or m
27dd0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
27de0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
27df0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
27e00 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
27e10 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
27e20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
27e30 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ces].**         
27e40 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
27e50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27e60 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
27e70 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  lumn.**         
27e80 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
27e90 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
27ea0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
27eb0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
27ec0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
27ed0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
27ee0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
27ef0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
27f00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
27f10 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
27f20 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
27f30 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
27f40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
27f50 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
27f60 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
27f70 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
27f80 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
27f90 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
27fa0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
27fb0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
27fc0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
27fd0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
27fe0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
27ff0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
28000 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
28010 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
28020 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28030 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
28040 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
28050 75 6c 74 20 7b 48 31 33 37 36 30 7d 20 3c 53 31  ult {H13760} <S1
28060 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0700>.**.** The 
28070 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
28080 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
28090 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
280a0 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
280b0 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
280c0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
280d0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
280e0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
280f0 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
28100 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
28110 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
28120 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
28130 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
28140 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
28150 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
28160 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
28170 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20 74 68  returned.  If th
28180 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
28190 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69  the result set i
281a0 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  s an.** expressi
281b0 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20  on or subquery, 
281c0 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  then a NULL poin
281d0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
281e0 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64  .** The returned
281f0 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
28200 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
28210 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72   {END}.**.** For
28220 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
28230 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
28240 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
28250 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
28260 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
28270 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
28280 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
28290 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
282a0 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
282b0 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
282c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
282d0 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
282e0 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
282f0 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
28300 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
28310 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
28320 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
28330 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
28340 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a  column (i==0)..*
28350 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
28360 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
28370 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75  e typing.  So ju
28380 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
28390 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
283a0 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
283b0 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
283c0 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
283d0 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
283e0 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
283f0 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
28400 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
28410 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
28420 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
28430 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
28440 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
28450 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73  .  Type.** is as
28460 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
28470 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
28480 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
28490 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
284a0 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
284b0 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  alues..**.** INV
284c0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
284d0 48 31 33 37 36 31 7d 20 20 41 20 73 75 63 63 65  H13761}  A succe
284e0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
284f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
28500 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20 72 65 74  cltype(S,N)] ret
28510 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  urns a.**       
28520 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
28530 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
28540 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
28550 64 65 63 6c 61 72 65 64 20 64 61 74 61 74 79 70  declared datatyp
28560 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f  e.**           o
28570 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
28580 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72 73 20  mn that appears 
28590 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  as the Nth colum
285a0 6e 20 28 6e 75 6d 62 65 72 65 64 0a 2a 2a 20 20  n (numbered.**  
285b0 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 30 29           from 0)
285c0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
285d0 65 74 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  et to the [prepa
285e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
285f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 32 7d  ..**.** {H13762}
28600 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63    A successful c
28610 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
28620 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
28630 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20  6(S,N)].**      
28640 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 7a       returns a z
28650 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
28660 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
28670 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67 0a 2a  e order string.*
28680 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  *           cont
28690 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61  aining the decla
286a0 72 65 64 20 64 61 74 61 74 79 70 65 20 6f 66 20  red datatype of 
286b0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
286c0 20 74 68 61 74 20 61 70 70 65 61 72 73 0a 2a 2a   that appears.**
286d0 20 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68             as th
286e0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75  e Nth column (nu
286f0 6d 62 65 72 65 64 20 66 72 6f 6d 20 30 29 20 6f  mbered from 0) o
28700 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
28710 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
28720 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
28730 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
28740 2a 2a 20 7b 48 31 33 37 36 33 7d 20 20 49 66 20  ** {H13763}  If 
28750 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 30  N is less than 0
28760 20 6f 72 20 4e 20 69 73 20 67 72 65 61 74 65 72   or N is greater
28770 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
28780 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  o.**           t
28790 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
287a0 75 6d 6e 73 20 69 6e 20 74 68 65 20 5b 70 72 65  umns in the [pre
287b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
287c0 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   S,.**          
287d0 20 6f 72 20 69 66 20 74 68 65 20 4e 74 68 20 63   or if the Nth c
287e0 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 6e  olumn of S is an
287f0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
28800 75 62 71 75 65 72 79 20 72 61 74 68 65 72 0a 2a  ubquery rather.*
28810 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61 6e  *           than
28820 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 2c   a table column,
28830 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20   or if a memory 
28840 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
28850 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  re.**           
28860 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 65 6e  occurs during en
28870 63 6f 64 69 6e 67 20 63 6f 6e 76 65 72 73 69 6f  coding conversio
28880 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  ns, then.**     
28890 20 20 20 20 20 20 63 61 6c 6c 73 20 74 6f 20 5b        calls to [
288a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
288b0 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20 6f 72  ecltype(S,N)] or
288c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
288d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
288e0 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 20 72  cltype16(S,N)] r
288f0 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63  eturn NULL..*/.c
28900 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
28910 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
28920 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
28930 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
28940 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
28950 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
28960 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
28970 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28980 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51  : Evaluate An SQ
28990 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33  L Statement {H13
289a0 32 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a  200} <S10000>.**
289b0 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
289c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
289d0 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
289e0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a  ed using either.
289f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
28a00 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
28a10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
28a20 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
28a30 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
28a40 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
28a50 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
28a60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28a70 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
28a80 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
28a90 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
28aa0 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
28ab0 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
28ac0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
28ad0 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
28ae0 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
28af0 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
28b00 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
28b10 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
28b20 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
28b30 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
28b40 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
28b50 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
28b60 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
28b70 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
28b80 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
28b90 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
28ba0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
28bb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
28bc0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
28bd0 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
28be0 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
28bf0 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
28c00 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
28c10 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
28c20 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
28c30 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
28c40 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
28c50 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
28c60 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65  .**.** In the le
28c70 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
28c80 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
28c90 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
28ca0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
28cb0 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
28cc0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
28cd0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
28ce0 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
28cf0 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22  ]..** With the "
28d00 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
28d10 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
28d20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
28d30 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
28d40 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
28d50 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
28d60 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53  s well..**.** [S
28d70 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
28d80 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
28d90 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
28da0 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
28db0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
28dc0 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
28dd0 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
28de0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
28df0 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a   is a [COMMIT].*
28e00 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
28e10 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
28e20 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
28e30 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
28e40 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
28e50 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
28e60 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
28e70 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63  [COMMIT] and occ
28e80 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20  urs within a.** 
28e90 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
28ea0 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68  tion then you sh
28eb0 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68  ould rollback th
28ec0 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
28ed0 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69  fore.** continui
28ee0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ng..**.** [SQLIT
28ef0 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
28f00 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
28f10 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
28f20 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
28f30 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
28f40 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
28f50 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
28f60 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
28f70 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
28f80 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
28f90 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
28fa0 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
28fb0 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
28fc0 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
28fd0 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
28fe0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
28ff0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
29000 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
29010 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
29020 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a  en [SQLITE_ROW].
29030 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  ** is returned e
29040 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
29050 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
29060 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69  ady for processi
29070 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ng by the.** cal
29080 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
29090 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
290a0 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d  using the [colum
290b0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
290c0 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
290d0 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
290e0 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
290f0 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
29100 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b  of data..**.** [
29110 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
29120 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
29130 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
29140 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
29150 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
29160 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
29170 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
29180 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
29190 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
291a0 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
291b0 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
291c0 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
291d0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
291e0 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c 65  ..** With the le
291f0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
29200 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
29210 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
29220 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
29230 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
29240 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
29250 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
29260 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
29270 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
29280 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
29290 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
292a0 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
292b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
292c0 20 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e    In the "v2" in
292d0 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
292e0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
292f0 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
29300 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
29310 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
29320 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
29330 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
29340 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
29350 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
29360 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
29370 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
29380 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
29390 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
293a0 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
293b0 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
293c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
293d0 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
293e0 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
293f0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
29400 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
29410 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
29420 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
29430 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
29440 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
29450 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29460 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
29470 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
29480 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
29490 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
294a0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e   time..**.** <b>
294b0 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
294c0 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
294d0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
294e0 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
294f0 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
29500 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
29510 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
29520 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
29530 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
29540 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
29550 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
29560 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
29570 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
29580 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
29590 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
295a0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
295b0 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
295c0 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
295d0 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
295e0 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
295f0 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
29600 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
29610 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
29620 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
29630 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
29640 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
29650 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
29660 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
29670 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
29680 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
29690 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
296a0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
296b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
296c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
296d0 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
296e0 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
296f0 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
29700 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
29710 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
29720 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
29730 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
29740 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
29750 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
29760 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
29770 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
29780 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
29790 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
297a0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
297b0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
297c0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 32 30 32 7d  :.**.** {H13202}
297d0 20 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72    If the [prepar
297e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
297f0 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  is ready to be r
29800 75 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  un, then.**     
29810 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
29820 74 65 70 28 53 29 5d 20 61 64 76 61 6e 63 65 73  tep(S)] advances
29830 20 74 68 61 74 20 70 72 65 70 61 72 65 64 20 73   that prepared s
29840 74 61 74 65 6d 65 6e 74 20 75 6e 74 69 6c 0a 2a  tatement until.*
29850 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f 6d 70  *           comp
29860 6c 65 74 69 6f 6e 20 6f 72 20 75 6e 74 69 6c 20  letion or until 
29870 69 74 20 69 73 20 72 65 61 64 79 20 74 6f 20 72  it is ready to r
29880 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f  eturn another ro
29890 77 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  w of the.**     
298a0 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74        result set
298b0 2c 20 6f 72 20 75 6e 74 69 6c 20 61 6e 20 5b 73  , or until an [s
298c0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
298d0 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 0a 2a 2a   | interrupt].**
298e0 20 20 20 20 20 20 20 20 20 20 20 6f 72 20 61 20             or a 
298f0 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 6f  run-time error o
29900 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ccurs..**.** {H1
29910 35 33 30 34 7d 20 20 57 68 65 6e 20 61 20 63 61  5304}  When a ca
29920 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
29930 74 65 70 28 53 29 5d 20 63 61 75 73 65 73 20 74  tep(S)] causes t
29940 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
29950 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20  tement].**      
29960 20 20 20 20 20 53 20 74 6f 20 72 75 6e 20 74 6f       S to run to
29970 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c 20 74 68 65   completion, the
29980 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
29990 73 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  s [SQLITE_DONE].
299a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 36 7d 20  .**.** {H15306} 
299b0 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20   When a call to 
299c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
299d0 5d 20 73 74 6f 70 73 20 62 65 63 61 75 73 65 20  ] stops because 
299e0 69 74 20 69 73 20 72 65 61 64 79 20 74 6f 0a 2a  it is ready to.*
299f0 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75  *           retu
29a00 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f  rn another row o
29a10 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
29a20 2c 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51  , it returns [SQ
29a30 4c 49 54 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a  LITE_ROW]..**.**
29a40 20 7b 48 31 35 33 30 38 7d 20 20 49 66 20 61 20   {H15308}  If a 
29a50 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
29a60 5f 73 74 65 70 28 53 29 5d 20 65 6e 63 6f 75 6e  _step(S)] encoun
29a70 74 65 72 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20  ters an.**      
29a80 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 69 6e       [sqlite3_in
29a90 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72  terrupt | interr
29aa0 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69  upt] or a run-ti
29ab0 6d 65 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20  me error,.**    
29ac0 20 20 20 20 20 20 20 69 74 20 72 65 74 75 72 6e         it return
29ad0 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
29ae0 20 65 72 72 6f 72 20 63 6f 64 65 20 74 68 61 74   error code that
29af0 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 0a 2a   is not one of.*
29b00 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  *           [SQL
29b10 49 54 45 5f 4f 4b 5d 2c 20 5b 53 51 4c 49 54 45  ITE_OK], [SQLITE
29b20 5f 52 4f 57 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  _ROW], or [SQLIT
29b30 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  E_DONE]..**.** {
29b40 48 31 35 33 31 30 7d 20 20 49 66 20 61 6e 20 5b  H15310}  If an [
29b50 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
29b60 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 20 6f  t | interrupt] o
29b70 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  r a run-time err
29b80 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
29b90 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 61 20  occurs during a 
29ba0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
29bb0 5f 73 74 65 70 28 53 29 5d 0a 2a 2a 20 20 20 20  _step(S)].**    
29bc0 20 20 20 20 20 20 20 66 6f 72 20 61 20 5b 70 72         for a [pr
29bd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29be0 5d 20 53 20 63 72 65 61 74 65 64 20 75 73 69 6e  ] S created usin
29bf0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6c  g.**           l
29c00 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 73  egacy interfaces
29c10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29c20 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  e()] or.**      
29c30 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72       [sqlite3_pr
29c40 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e  epare16()], then
29c50 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   the function re
29c60 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
29c70 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
29c80 45 5f 45 52 52 4f 52 5d 2c 20 5b 53 51 4c 49 54  E_ERROR], [SQLIT
29c90 45 5f 42 55 53 59 5d 2c 20 6f 72 20 5b 53 51 4c  E_BUSY], or [SQL
29ca0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2f 0a  ITE_MISUSE]..*/.
29cb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
29cc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
29cd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29ce0 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
29cf0 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
29d00 73 65 74 20 7b 48 31 33 37 37 30 7d 20 3c 53 31  set {H13770} <S1
29d10 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75  0700>.**.** Retu
29d20 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
29d30 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20  f values in the 
29d40 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
29d50 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a  he result set..*
29d60 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
29d70 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 37 31 7d 20  .**.** {H13771} 
29d80 20 41 66 74 65 72 20 61 20 63 61 6c 6c 20 74 6f   After a call to
29d90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
29da0 29 5d 20 74 68 61 74 20 72 65 74 75 72 6e 73 20  )] that returns 
29db0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 0a 2a 2a  [SQLITE_ROW],.**
29dc0 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b             the [
29dd0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
29de0 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e 65 20 77  nt(S)] routine w
29df0 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 73  ill return the s
29e00 61 6d 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20  ame value.**    
29e10 20 20 20 20 20 20 20 61 73 20 74 68 65 20 5b 73         as the [s
29e20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
29e30 75 6e 74 28 53 29 5d 20 66 75 6e 63 74 69 6f 6e  unt(S)] function
29e40 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 37 32 7d  ..**.** {H13772}
29e50 20 20 41 66 74 65 72 20 5b 73 71 6c 69 74 65 33    After [sqlite3
29e60 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 72 65  _step(S)] has re
29e70 74 75 72 6e 65 64 20 61 6e 79 20 76 61 6c 75 65  turned any value
29e80 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20   other than.**  
29e90 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
29ea0 5f 52 4f 57 5d 20 6f 72 20 62 65 66 6f 72 65 20  _ROW] or before 
29eb0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
29ec0 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
29ed0 64 20 6f 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  d on the.**     
29ee0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
29ef0 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f 72 20 74  statement] for t
29f00 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 69  he first time si
29f10 6e 63 65 20 69 74 20 77 61 73 0a 2a 2a 20 20 20  nce it was.**   
29f20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
29f30 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
29f40 72 65 64 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  red] or [sqlite3
29f50 5f 72 65 73 65 74 20 7c 20 72 65 73 65 74 5d 2c  _reset | reset],
29f60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
29f70 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  e [sqlite3_data_
29f80 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e  count(S)] routin
29f90 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  e returns zero..
29fa0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
29fb0 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
29fc0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
29fd0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29fe0 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
29ff0 61 74 79 70 65 73 20 7b 48 31 30 32 36 35 7d 20  atypes {H10265} 
2a000 3c 53 31 30 31 31 30 3e 3c 53 31 30 31 32 30 3e  <S10110><S10120>
2a010 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
2a020 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
2a030 7b 48 31 30 32 36 36 7d 20 45 76 65 72 79 20 76  {H10266} Every v
2a040 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
2a050 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
2a060 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
2a070 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
2a080 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
2a090 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
2a0a0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
2a0b0 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
2a0c0 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
2a0d0 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
2a0e0 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
2a0f0 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d  L.** </ul> {END}
2a100 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2a110 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
2a120 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
2a130 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
2a140 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
2a150 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
2a160 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
2a170 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
2a180 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
2a190 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
2a1a0 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
2a1b0 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
2a1c0 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
2a1d0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2a1e0 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
2a1f0 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
2a200 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20  e SQLITE3_TEXT, 
2a210 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
2a220 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
2a230 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
2a240 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a250 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
2a260 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
2a270 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
2a280 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
2a290 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
2a2a0 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
2a2b0 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
2a2c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
2a2d0 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
2a2e0 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
2a2f0 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
2a300 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
2a310 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
2a320 75 65 72 79 20 7b 48 31 33 38 30 30 7d 20 3c 53  uery {H13800} <S
2a330 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  10700>.** KEYWOR
2a340 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
2a350 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
2a360 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2a370 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73  es form the "res
2a380 75 6c 74 20 73 65 74 20 71 75 65 72 79 22 20 69  ult set query" i
2a390 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2a3a0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2a3b0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2a3c0 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
2a3d0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
2a3e0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
2a3f0 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
2a400 20 20 49 6e 20 65 76 65 72 79 20 63 61 73 65 20    In every case 
2a410 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2a420 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a  nt is a pointer.
2a430 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  ** to the [prepa
2a440 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2a450 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61  hat is being eva
2a460 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c  luated (the [sql
2a470 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74  ite3_stmt*].** t
2a480 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
2a490 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70   from [sqlite3_p
2a4a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2a4b0 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
2a4c0 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  nts).** and the 
2a4d0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2a4e0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
2a4f0 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
2a500 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
2a510 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
2a520 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 66  turned.  The lef
2a530 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  tmost column of 
2a540 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68  the result set h
2a550 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a  as the index 0..
2a560 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
2a570 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
2a580 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
2a590 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
2a5a0 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
2a5b0 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
2a5c0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
2a5d0 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
2a5e0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65  efined..** These
2a5f0 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
2a600 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
2a610 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
2a620 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
2a630 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2a640 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
2a650 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
2a660 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
2a670 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
2a680 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2a690 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  ] have been call
2a6a0 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ed subsequently.
2a6b0 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
2a6c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2a6d0 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
2a6e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2a6f0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
2a700 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
2a710 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
2a720 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
2a730 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
2a740 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2a750 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
2a760 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2a770 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
2a780 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
2a790 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2a7a0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2a7b0 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
2a7c0 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
2a7d0 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
2a7e0 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
2a7f0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
2a800 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
2a810 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2a820 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
2a830 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2a840 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
2a850 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
2a860 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
2a870 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
2a880 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
2a890 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
2a8a0 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
2a8b0 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65  mn.  The returne
2a8c0 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
2a8d0 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
2a8e0 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
2a8f0 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
2a900 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
2a910 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
2a920 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
2a930 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
2a940 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a950 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
2a960 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
2a970 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
2a980 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
2a990 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
2a9a0 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
2a9b0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
2a9c0 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
2a9d0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2a9e0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2a9f0 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
2aa00 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
2aa10 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
2aa20 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
2aa30 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
2aa40 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
2aa50 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
2aa60 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
2aa70 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20  * If the result 
2aa80 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
2aa90 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  -8 string then t
2aaa0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2aab0 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75  n_bytes().** rou
2aac0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2aad0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2aae0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
2aaf0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74   string..** If t
2ab00 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2ab10 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
2ab20 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2ab30 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
2ab40 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2ab50 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
2ab60 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2ab70 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2ab80 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
2ab90 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
2aba0 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
2abb0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2abc0 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
2abd0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
2abe0 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
2abf0 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
2ac00 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2ac10 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2ac20 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2ac30 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76  string..** The v
2ac40 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f  alue returned do
2ac50 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  es not include t
2ac60 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
2ac70 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  or at the end.**
2ac80 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
2ac90 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68   For clarity: th
2aca0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
2acb0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
2acc0 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
2acd0 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
2ace0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
2acf0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74  acters..**.** St
2ad00 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
2ad10 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2ad20 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
2ad30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2ad40 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
2ad50 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
2ad60 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d  always zero term
2ad70 69 6e 61 74 65 64 2e 20 20 54 68 65 20 72 65 74  inated.  The ret
2ad80 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
2ad90 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
2ada0 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
2adb0 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
2adc0 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a  s an arbitrary.*
2add0 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69  * pointer, possi
2ade0 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20  bly even a NULL 
2adf0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
2ae00 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2ae10 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75 74  n_bytes16() rout
2ae20 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
2ae30 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2ae40 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20  _bytes().** but 
2ae50 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 75 6c  leaves the resul
2ae60 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e  t in UTF-16 in n
2ae70 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2ae80 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d   instead of UTF-
2ae90 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74  8..** The zero t
2aea0 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74  erminator is not
2aeb0 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69   included in thi
2aec0 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  s count..**.** T
2aed0 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
2aee0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2aef0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2af00 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
2af10 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2af20 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
2af30 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2af40 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2af50 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
2af60 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
2af70 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
2af80 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
2af90 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
2afa0 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
2afb0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2afc0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
2afd0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
2afe0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2aff0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
2b000 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
2b010 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
2b020 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
2b030 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2b040 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
2b050 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2b060 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
2b070 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
2b080 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2b090 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
2b0a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2b0b0 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
2b0c0 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2b0d0 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
2b0e0 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ate.  For.** exa
2b0f0 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74  mple, if the int
2b100 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
2b110 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e  tion is FLOAT an
2b120 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a  d a text result.
2b130 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c  ** is requested,
2b140 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2b150 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  tf()] is used in
2b160 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66  ternally to perf
2b170 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65  orm the.** conve
2b180 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61  rsion automatica
2b190 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77  lly.  The follow
2b1a0 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
2b1b0 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
2b1c0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
2b1d0 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
2b1e0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
2b1f0 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
2b200 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
2b210 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
2b220 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
2b230 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
2b240 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
2b250 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2b260 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2b270 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
2b280 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2b290 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2b2a0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2b2b0 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
2b2c0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
2b2d0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
2b2e0 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  ult is NULL poin
2b2f0 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
2b300 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
2b310 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73  BLOB    <td> Res
2b320 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  ult is NULL poin
2b330 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
2b340 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
2b350 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
2b360 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
2b370 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
2b380 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2b390 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2b3a0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
2b3b0 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
2b3c0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
2b3d0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
2b3e0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
2b3f0 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58   as INTEGER->TEX
2b400 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
2b410 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
2b420 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
2b430 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f  rt from float to
2b440 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
2b450 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2b460 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2b470 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
2b480 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a  g of the float.*
2b490 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2b4a0 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  T   <td>   BLOB 
2b4b0 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
2b4c0 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c  FLOAT->TEXT.** <
2b4d0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2b4e0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2b4f0 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a  <td> Use atoi().
2b500 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
2b510 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  T    <td>  FLOAT
2b520 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f      <td> Use ato
2b530 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
2b540 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20   TEXT    <td>   
2b550 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20  BLOB    <td> No 
2b560 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74  change.** <tr><t
2b570 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2b580 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2b590 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
2b5a0 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a  then use atoi().
2b5b0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2b5c0 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
2b5d0 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
2b5e0 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
2b5f0 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
2b600 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2b610 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2b620 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72  > Add a zero ter
2b630 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65  minator if neede
2b640 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  d.** </table>.**
2b650 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a   </blockquote>.*
2b660 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61  *.** The table a
2b670 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72  bove makes refer
2b680 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64  ence to standard
2b690 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74   C library funct
2b6a0 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61  ions atoi().** a
2b6b0 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69  nd atof().  SQLi
2b6c0 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c  te does not real
2b6d0 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e  ly use these fun
2b6e0 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20  ctions.  It has 
2b6f0 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76  its.** own equiv
2b700 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72  alent internal r
2b710 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74  outines.  The at
2b720 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20  oi() and atof() 
2b730 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  names are.** use
2b740 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66  d in the table f
2b750 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62  or brevity and b
2b760 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20  ecause they are 
2b770 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74  familiar to most
2b780 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72  .** C programmer
2b790 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
2b7a0 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
2b7b0 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
2b7c0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2b7d0 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
2b7e0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2b7f0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
2b800 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2b810 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
2b820 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2b830 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
2b840 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
2b850 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
2b860 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
2b870 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
2b880 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
2b890 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
2b8a0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2b8b0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2b8c0 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
2b8d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2b8e0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
2b8f0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2b900 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2b910 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
2b920 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
2b930 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
2b940 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
2b950 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
2b960 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2b970 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
2b980 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
2b990 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2b9a0 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
2b9b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b9c0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2b9d0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
2b9e0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
2b9f0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
2ba00 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
2ba10 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2ba20 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
2ba30 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2ba40 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2ba50 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2ba60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2ba70 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
2ba80 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
2ba90 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
2baa0 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
2bab0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
2bac0 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65  * Conversions be
2bad0 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61  tween UTF-16be a
2bae0 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20  nd UTF-16le are 
2baf0 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70  always done in p
2bb00 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e  lace and do.** n
2bb10 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20  ot invalidate a 
2bb20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74  prior pointer, t
2bb30 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
2bb40 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2bb50 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  he buffer.** tha
2bb60 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
2bb70 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 69  ter points to wi
2bb80 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
2bb90 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
2bba0 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
2bbb0 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
2bbc0 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
2bbd0 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
2bbe0 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a  sometimes they.*
2bbf0 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62  * are not possib
2bc00 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
2bc10 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
2bc20 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
2bc30 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
2bc40 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65  safest and easie
2bc50 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70  st to remember p
2bc60 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
2bc70 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
2bc80 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
2bc90 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
2bca0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2bcb0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
2bcc0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
2bcd0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2bce0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
2bcf0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
2bd00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2bd10 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2bd20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2bd30 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
2bd40 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2bd50 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
2bd60 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2bd70 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
2bd80 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
2bd90 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
2bda0 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
2bdb0 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
2bdc0 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
2bdd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2bde0 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
2bdf0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
2be00 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
2be10 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
2be20 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
2be30 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
2be40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2be50 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
2be60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2be70 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
2be80 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
2be90 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
2bea0 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
2beb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2bec0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2bed0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
2bee0 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
2bef0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2bf00 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
2bf10 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
2bf20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bf30 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
2bf40 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2bf50 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2bf60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
2bf70 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
2bf80 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
2bf90 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
2bfa0 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
2bfb0 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
2bfc0 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
2bfd0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2bfe0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
2bff0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2c000 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
2c010 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 73  d.  The memory s
2c020 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
2c030 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
2c040 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
2c050 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2c060 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61  Do <b>not</b> pa
2c070 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
2c080 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c  returned.** [sql
2c090 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2c0a0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
2c0b0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
2c0c0 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
2c0d0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
2c0e0 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61  ** If a memory a
2c0f0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
2c100 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
2c110 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
2c120 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
2c130 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
2c140 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
2c150 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
2c160 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
2c170 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
2c180 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
2c190 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
2c1a0 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
2c1b0 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
2c1c0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
2c1d0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
2c1e0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
2c1f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
2c200 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
2c210 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  NTS:.**.** {H138
2c220 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  03} The [sqlite3
2c230 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e  _column_blob(S,N
2c240 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2c250 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2c260 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
2c270 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
2c280 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2c290 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
2c2a0 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61        the [prepa
2c2b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2c2c0 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61 6e 64   into a BLOB and
2c2d0 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 61 0a   then returns a.
2c2e0 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e  **          poin
2c2f0 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65  ter to the conve
2c300 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  rted value..**.*
2c310 2a 20 7b 48 31 33 38 30 36 7d 20 54 68 65 20 5b  * {H13806} The [
2c320 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c330 79 74 65 73 28 53 2c 4e 29 5d 20 69 6e 74 65 72  ytes(S,N)] inter
2c340 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2c350 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
2c360 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2c370 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
2c380 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66  ng (exclusive of
2c390 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c3a0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2c3b0 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20   on the string) 
2c3c0 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
2c3d0 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
2c3e0 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74       most recent
2c3f0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2c400 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c  3_column_blob(S,
2c410 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  N)] or.**       
2c420 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
2c430 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 2e 0a 2a  mn_text(S,N)]..*
2c440 2a 0a 2a 2a 20 7b 48 31 33 38 30 39 7d 20 54 68  *.** {H13809} Th
2c450 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2c460 6e 5f 62 79 74 65 73 31 36 28 53 2c 4e 29 5d 20  n_bytes16(S,N)] 
2c470 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2c480 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2c490 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65    number of byte
2c4a0 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20  s in the string 
2c4b0 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68  (exclusive of th
2c4c0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
2c4d0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e  ro terminator on
2c4e0 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61   the string) tha
2c4f0 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62  t was returned b
2c500 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
2c510 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61    most recent ca
2c520 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2c530 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e  olumn_text16(S,N
2c540 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31  )]..**.** {H1381
2c550 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2c560 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 53 2c  column_double(S,
2c570 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
2c580 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2c590 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
2c5a0 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
2c5b0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2c5c0 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a  lt set for the.*
2c5d0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2c5e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2c5f0 53 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e  S into a floatin
2c600 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e  g point value an
2c610 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
2c620 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  turns a copy of 
2c630 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  that value..**.*
2c640 2a 20 7b 48 31 33 38 31 35 7d 20 54 68 65 20 5b  * {H13815} The [
2c650 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2c660 6e 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  nt(S,N)] interfa
2c670 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2c680 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
2c690 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
2c6a0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2c6b0 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20   result set for 
2c6c0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2c6d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c6e0 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34  ent] S into a 64
2c6f0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2c700 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ger and.**      
2c710 20 20 20 20 72 65 74 75 72 6e 73 20 74 68 65 20      returns the 
2c720 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f 66  lower 32 bits of
2c730 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a   that integer..*
2c740 2a 0a 2a 2a 20 7b 48 31 33 38 31 38 7d 20 54 68  *.** {H13818} Th
2c750 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2c760 6e 5f 69 6e 74 36 34 28 53 2c 4e 29 5d 20 69 6e  n_int64(S,N)] in
2c770 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
2c780 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c790 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
2c7a0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
2c7b0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2c7c0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
2c7d0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
2c7e0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
2c7f0 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64   a 64-bit signed
2c800 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20   integer and.** 
2c810 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
2c820 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20   a copy of that 
2c830 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  integer..**.** {
2c840 48 31 33 38 32 31 7d 20 54 68 65 20 5b 73 71 6c  H13821} The [sql
2c850 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c860 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
2c870 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2c880 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
2c890 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
2c8a0 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
2c8b0 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a  esult set for.**
2c8c0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70            the [p
2c8d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c8e0 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f  t] S into a zero
2c8f0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
2c900 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  8.**          st
2c910 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2c920 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2c930 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
2c940 20 7b 48 31 33 38 32 34 7d 20 54 68 65 20 5b 73   {H13824} The [s
2c950 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c960 78 74 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  xt16(S,N)] inter
2c970 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2c980 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
2c990 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
2c9a0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
2c9b0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
2c9c0 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
2c9d0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
2c9e0 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
2c9f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2ca00 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20  2-byte.**       
2ca10 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31     aligned UTF-1
2ca20 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
2ca30 64 65 72 20 73 74 72 69 6e 67 20 61 6e 64 20 72  der string and r
2ca40 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
2ca50 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20     a pointer to 
2ca60 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
2ca70 2a 2a 20 7b 48 31 33 38 32 37 7d 20 54 68 65 20  ** {H13827} The 
2ca80 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2ca90 74 79 70 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  type(S,N)] inter
2caa0 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
2cab0 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20           one of 
2cac0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b  [SQLITE_NULL], [
2cad0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
2cae0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
2caf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
2cb00 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b  LITE_TEXT], or [
2cb10 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20  SQLITE_BLOB] as 
2cb20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a  appropriate for.
2cb30 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2cb40 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
2cb50 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
2cb60 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2cb70 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
2cb80 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2cb90 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a  atement] S..**.*
2cba0 2a 20 7b 48 31 33 38 33 30 7d 20 54 68 65 20 5b  * {H13830} The [
2cbb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2cbc0 61 6c 75 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  alue(S,N)] inter
2cbd0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 0a 2a  face returns a.*
2cbe0 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
2cbf0 65 72 20 74 6f 20 61 6e 20 5b 75 6e 70 72 6f 74  er to an [unprot
2cc00 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2cc10 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 20  lue] object for 
2cc20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2cc30 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
2cc40 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
2cc50 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2cc60 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
2cc70 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2cc80 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 63  atement] S..*/.c
2cc90 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2cca0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
2ccb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2ccc0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
2ccd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2cce0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
2ccf0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2cd00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2cd10 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
2cd20 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2cd30 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
2cd40 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
2cd50 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2cd60 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
2cd70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73  te3_column_int(s
2cd80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2cd90 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
2cda0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63  _int64 sqlite3_c
2cdb0 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69  olumn_int64(sqli
2cdc0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2cdd0 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  Col);.const unsi
2cde0 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
2cdf0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73  e3_column_text(s
2ce00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2ce10 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76  t iCol);.const v
2ce20 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2ce30 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74  umn_text16(sqlit
2ce40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2ce50 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2ce60 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
2ce70 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2ce80 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76  iCol);.sqlite3_v
2ce90 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f  alue *sqlite3_co
2cea0 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74  lumn_value(sqlit
2ceb0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2cec0 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
2ced0 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
2cee0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2cef0 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 30  nt Object {H1330
2cf00 30 7d 20 3c 53 37 30 33 30 30 3e 3c 53 33 30 31  0} <S70300><S301
2cf10 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
2cf20 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2cf30 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
2cf40 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
2cf50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2cf60 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ent]..** If the 
2cf70 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78  statement was ex
2cf80 65 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75  ecuted successfu
2cf90 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75  lly or not execu
2cfa0 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e  ted at all, then
2cfb0 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73  .** SQLITE_OK is
2cfc0 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20 65 78   returned. If ex
2cfd0 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  ecution of the s
2cfe0 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20  tatement failed 
2cff0 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  then an.** [erro
2d000 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65  r code] or [exte
2d010 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
2d020 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2d030 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
2d040 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
2d050 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
2d060 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
2d070 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   of the.** [prep
2d080 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2d090 20 20 49 66 20 74 68 65 20 76 69 72 74 75 61 6c    If the virtual
2d0a0 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74   machine has not
2d0b0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78  .** completed ex
2d0c0 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69  ecution when thi
2d0d0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  s routine is cal
2d0e0 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b  led, that is lik
2d0f0 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e  e.** encounterin
2d100 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e  g an error or an
2d110 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
2d120 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d  upt | interrupt]
2d130 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20  ..** Incomplete 
2d140 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72  updates may be r
2d150 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74  olled back and t
2d160 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63  ransactions canc
2d170 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69  eled,.** dependi
2d180 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d  ng on the circum
2d190 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65  stances, and the
2d1a0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
2d1b0 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62   returned will b
2d1c0 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  e [SQLITE_ABORT]
2d1d0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2d1e0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30  TS:.**.** {H1130
2d1f0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2d200 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 6e 74  finalize(S)] int
2d210 65 72 66 61 63 65 20 64 65 73 74 72 6f 79 73 20  erface destroys 
2d220 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2d230 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d240 65 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c 65 61  ent] S and relea
2d250 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  ses all.**      
2d260 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20 66      memory and f
2d270 69 6c 65 20 72 65 73 6f 75 72 63 65 73 20 68 65  ile resources he
2d280 6c 64 20 62 79 20 74 68 61 74 20 6f 62 6a 65 63  ld by that objec
2d290 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 34  t..**.** {H11304
2d2a0 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  } If the most re
2d2b0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2d2c0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2d2d0 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
2d2e0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
2d2f0 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
2d300 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a 2a 20  ed an error,.** 
2d310 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73           then [s
2d320 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2d330 53 29 5d 20 72 65 74 75 72 6e 73 20 74 68 61 74  S)] returns that
2d340 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a 2f 0a   same error..*/.
2d350 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
2d360 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
2d370 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2d380 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2d390 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
2d3a0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48  tement Object {H
2d3b0 31 33 33 33 30 7d 20 3c 53 37 30 33 30 30 3e 0a  13330} <S70300>.
2d3c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2d3d0 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
2d3e0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2d3f0 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65  reset a [prepare
2d400 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2d410 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69  object back to i
2d420 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
2d430 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
2d440 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e  -executed..** An
2d450 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
2d460 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
2d470 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
2d480 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
2d490 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2d4a0 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
2d4b0 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
2d4c0 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
2d4d0 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
2d4e0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
2d4f0 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
2d500 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
2d510 0a 2a 2a 20 7b 48 31 31 33 33 32 7d 20 54 68 65  .** {H11332} The
2d520 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2d530 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
2d540 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
2d550 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
2d560 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61 63 6b  **          back
2d570 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   to the beginnin
2d580 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d  g of its program
2d590 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 7d  ..**.** {H11334}
2d5a0 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   If the most rec
2d5b0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2d5c0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
2d5d0 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
2d5e0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
2d5f0 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
2d600 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
2d610 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
2d620 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
2d630 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
2d640 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
2d650 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
2d660 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20  d on S,.**      
2d670 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65      then [sqlite
2d680 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
2d690 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
2d6a0 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 36 7d 20  .**.** {H11336} 
2d6b0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2d6c0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2d6d0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
2d6e0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2d6f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d700 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65  ment] S indicate
2d710 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e  d an error, then
2d720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2d730 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2d740 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
2d750 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
2d760 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  de]..**.** {H113
2d770 33 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  38} The [sqlite3
2d780 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
2d790 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68  face does not ch
2d7a0 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a  ange the values.
2d7b0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61  **          of a
2d7c0 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
2d7d0 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
2d7e0 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
2d7f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
2d800 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
2d810 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
2d820 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2d830 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
2d840 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
2d850 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36  L Functions {H16
2d860 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  100} <S20200>.**
2d870 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
2d880 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
2d890 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
2d8a0 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
2d8b0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2d8c0 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
2d8d0 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
2d8e0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2d8f0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
2d900 68 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f  hese two functio
2d910 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79  ns (collectively
2d920 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74   known as "funct
2d930 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
2d940 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75  tines").** are u
2d950 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66  sed to add SQL f
2d960 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
2d970 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64  egates or to red
2d980 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69  efine the behavi
2d990 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e  or.** of existin
2d9a0 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  g SQL functions 
2d9b0 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  or aggregates.  
2d9c0 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65  The only differe
2d9d0 6e 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a  nce between the.
2d9e0 2a 2a 20 74 77 6f 20 69 73 20 74 68 61 74 20 74  ** two is that t
2d9f0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2da00 74 65 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66  ter, the name of
2da10 20 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75   the (scalar) fu
2da20 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
2da30 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64  regate, is encod
2da40 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20  ed in UTF-8 for 
2da50 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2da60 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54  unction() and UT
2da70 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  F-16.** for sqli
2da80 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2da90 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  ion16()..**.** T
2daa0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2dab0 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
2dac0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2dad0 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
2dae0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
2daf0 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 49 66  to be added.  If
2db00 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 61   a single progra
2db10 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  m uses more than
2db20 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
2db30 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65   connection inte
2db40 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c  rnally, then SQL
2db50 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
2db60 62 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 64  be added individ
2db70 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68  ually to.** each
2db80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2db90 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
2dba0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2dbb0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
2dbc0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2dbd0 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f   to be created o
2dbe0 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20  r.** redefined. 
2dbf0 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   The length of t
2dc00 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
2dc10 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c  ed to 255 bytes,
2dc20 20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a   exclusive of.**
2dc30 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
2dc40 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74  ator.  Note that
2dc50 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68   the name length
2dc60 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74   limit is in byt
2dc70 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61  es, not.** chara
2dc80 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65  cters.  Any atte
2dc90 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
2dca0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
2dcb0 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
2dcc0 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53  ill result in [S
2dcd0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69  QLITE_ERROR] bei
2dce0 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
2dcf0 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70 61 72  ** The third par
2dd00 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
2dd10 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
2dd20 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
2dd30 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2dd40 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2dd50 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73  e takes. If this
2dd60 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65   parameter is ne
2dd70 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
2dd80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2dd90 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
2dda0 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
2ddb0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a  r of arguments..
2ddc0 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68  **.** The fourth
2ddd0 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
2dde0 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
2ddf0 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
2de00 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
2de10 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
2de20 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
2de30 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
2de40 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20  eters.  Any SQL 
2de50 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2de60 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  ntation should b
2de70 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a  e able to work.*
2de80 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d  * work with UTF-
2de90 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20  8, UTF-16le, or 
2dea0 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73  UTF-16be.  But s
2deb0 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ome implementati
2dec0 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f  ons may be.** mo
2ded0 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74  re efficient wit
2dee0 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74  h one encoding t
2def0 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74  han another.  It
2df00 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a   is allowed to.*
2df10 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
2df20 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2df30 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
2df40 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2df50 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
2df60 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
2df70 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
2df80 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
2df90 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
2dfa0 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70  ..** When multip
2dfb0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2dfc0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
2dfd0 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69  unction are avai
2dfe0 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a  lable, SQLite.**
2dff0 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f   will pick the o
2e000 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73  ne that involves
2e010 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
2e020 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72  t of data conver
2e030 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72  sion..** If ther
2e040 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67  e is only a sing
2e050 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2e060 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74  n which does not
2e070 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a   care what text.
2e080 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  ** encoding is u
2e090 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  sed, then the fo
2e0a0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68  urth argument sh
2e0b0 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f  ould be [SQLITE_
2e0c0 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ANY]..**.** The 
2e0d0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
2e0e0 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
2e0f0 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
2e100 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2e110 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
2e120 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
2e130 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
2e140 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
2e150 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a  ser_data()]..**.
2e160 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20  ** The seventh, 
2e170 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68  eighth and ninth
2e180 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75   parameters, xFu
2e190 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46  nc, xStep and xF
2e1a0 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69  inal, are.** poi
2e1b0 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75  nters to C-langu
2e1c0 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  age functions th
2e1d0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
2e1e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2e1f0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 41  .** aggregate. A
2e200 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
2e210 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
2e220 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e230 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20  of the xFunc.** 
2e240 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e  callback only, N
2e250 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f  ULL pointers sho
2e260 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73  uld be passed as
2e270 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
2e280 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
2e290 65 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74  ers. An aggregat
2e2a0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
2e2b0 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
2e2c0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74  mentation of xSt
2e2d0 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
2e2e0 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64   and NULL should
2e2f0 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78   be passed for x
2e300 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20  Func. To delete 
2e310 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53  an existing.** S
2e320 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
2e330 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e  ggregate, pass N
2e340 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ULL for all thre
2e350 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  e function callb
2e360 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  acks..**.** It i
2e370 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
2e380 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
2e390 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2e3a0 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
2e3b0 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
2e3c0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
2e3d0 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
2e3e0 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
2e3f0 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
2e400 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66  r differing pref
2e410 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
2e420 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69  ings.  SQLite wi
2e430 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
2e440 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73  plementation mos
2e450 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65  t closely matche
2e460 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69  s the way in whi
2e470 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75  ch the.** SQL fu
2e480 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20  nction is used. 
2e490 20 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   A function impl
2e4a0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
2e4b0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
2e4c0 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
2e4d0 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
2e4e0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
2e4f0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2e500 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61  n with.** a nega
2e510 74 69 76 65 20 6e 41 72 67 2e 20 20 41 20 66 75  tive nArg.  A fu
2e520 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
2e530 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
2e540 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
2e550 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
2e560 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
2e570 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
2e580 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
2e590 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
2e5a0 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
2e5b0 20 0a 2a 2a 20 41 20 66 75 6e 63 74 69 6f 6e 20   .** A function 
2e5c0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
2e5d0 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
2e5e0 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
2e5f0 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
2e600 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
2e610 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
2e620 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
2e630 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
2e640 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
2e650 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
2e660 0a 2a 2a 20 42 75 69 6c 74 2d 69 6e 20 66 75 6e  .** Built-in fun
2e670 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76  ctions may be ov
2e680 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20  erloaded by new 
2e690 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2e6a0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ned functions..*
2e6b0 2a 20 54 68 65 20 66 69 72 73 74 20 61 70 70 6c  * The first appl
2e6c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e6d0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
2e6e0 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72 72  given name overr
2e6f0 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c  ides all.** buil
2e700 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 69  t-in functions i
2e710 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
2e720 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2e730 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
2e740 61 6d 65 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  ame..** Subseque
2e750 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  nt application-d
2e760 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
2e770 20 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61 6d   of the same nam
2e780 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65 20  e only override 
2e790 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c 69 63  .** prior applic
2e7a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2e7b0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  nctions that are
2e7c0 20 61 6e 20 65 78 61 63 74 20 6d 61 74 63 68 20   an exact match 
2e7d0 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  for the.** numbe
2e7e0 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20  r of parameters 
2e7f0 61 6e 64 20 70 72 65 66 65 72 72 65 64 20 65 6e  and preferred en
2e800 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e  coding..**.** An
2e810 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2e820 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
2e830 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
2e840 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
2e850 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
2e860 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
2e870 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
2e880 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
2e890 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
2e8a0 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
2e8b0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
2e8c0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
2e8d0 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
2e8e0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2e8f0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2e900 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 33 7d  :.**.** {H16103}
2e910 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   The [sqlite3_cr
2e920 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2e930 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  D,X,...)] interf
2e940 61 63 65 20 73 68 61 6c 6c 20 62 65 68 61 76 65  ace shall behave
2e950 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20  .**          as 
2e960 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2e970 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e  function(D,X,...
2e980 29 5d 20 69 6e 20 65 76 65 72 79 20 77 61 79 20  )] in every way 
2e990 65 78 63 65 70 74 20 74 68 61 74 20 69 74 0a 2a  except that it.*
2e9a0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
2e9b0 70 72 65 74 73 20 74 68 65 20 58 20 61 72 67 75  prets the X argu
2e9c0 6d 65 6e 74 20 61 73 20 7a 65 72 6f 2d 74 65 72  ment as zero-ter
2e9d0 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 0a 2a  minated UTF-16.*
2e9e0 2a 20 20 20 20 20 20 20 20 20 20 6e 61 74 69 76  *          nativ
2e9f0 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73  e byte order ins
2ea00 74 65 61 64 20 6f 66 20 61 73 20 7a 65 72 6f 2d  tead of as zero-
2ea10 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
2ea20 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 36 7d  ..**.** {H16106}
2ea30 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
2ea40 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  vocation of the.
2ea50 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2ea60 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2ea70 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e  tion(D,X,N,E,...
2ea80 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  )] interface sha
2ea90 6c 6c 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 20  ll register.**  
2eaa0 20 20 20 20 20 20 20 20 6f 72 20 72 65 70 6c 61          or repla
2eab0 63 65 73 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ces callback fun
2eac0 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 5b 64  ctions in the [d
2ead0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2eae0 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20  on] D.**        
2eaf0 20 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d    used to implem
2eb00 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
2eb10 74 69 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69 74  tion named X wit
2eb20 68 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  h N parameters.*
2eb30 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 68  *          and h
2eb40 61 76 69 6e 67 20 61 20 70 72 65 66 65 72 72 65  aving a preferre
2eb50 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  d text encoding 
2eb60 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  of E..**.** {H16
2eb70 31 30 39 7d 20 41 20 73 75 63 63 65 73 73 66 75  109} A successfu
2eb80 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
2eb90 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2eba0 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53  on(D,X,N,E,P,F,S
2ebb0 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,L)].**         
2ebc0 20 73 68 61 6c 6c 20 72 65 70 6c 61 63 65 20 74   shall replace t
2ebd0 68 65 20 50 2c 20 46 2c 20 53 2c 20 61 6e 64 20  he P, F, S, and 
2ebe0 4c 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 61 6e  L values from an
2ebf0 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69  y prior calls wi
2ec00 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  th.**          t
2ec10 68 65 20 73 61 6d 65 20 44 2c 20 58 2c 20 4e 2c  he same D, X, N,
2ec20 20 61 6e 64 20 45 20 76 61 6c 75 65 73 2e 0a 2a   and E values..*
2ec30 2a 0a 2a 2a 20 7b 48 31 36 31 31 32 7d 20 54 68  *.** {H16112} Th
2ec40 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2ec50 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e  e_function(D,X,.
2ec60 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73  ..)] interface s
2ec70 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20  hall fail.**    
2ec80 20 20 20 20 20 20 69 66 20 74 68 65 20 53 51 4c        if the SQL
2ec90 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 20 58   function name X
2eca0 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
2ecb0 6c 6f 6e 67 65 72 20 74 68 61 6e 20 32 35 35 20  longer than 255 
2ecc0 62 79 74 65 73 20 65 78 63 6c 75 73 69 76 65 20  bytes exclusive 
2ecd0 6f 66 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  of the zero term
2ece0 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  inator..**.** {H
2ecf0 31 36 31 31 38 7d 20 54 68 65 20 5b 73 71 6c 69  16118} The [sqli
2ed00 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2ed10 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  ion(D,X,N,E,P,F,
2ed20 53 2c 4c 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  S,L)] interface.
2ed30 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
2ed40 6c 20 66 61 69 6c 20 75 6e 6c 65 73 73 20 65 69  l fail unless ei
2ed50 74 68 65 72 20 46 20 69 73 20 4e 55 4c 4c 20 61  ther F is NULL a
2ed60 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20 6e  nd S and L are n
2ed70 6f 6e 2d 4e 55 4c 4c 20 6f 72 0a 2a 2a 2a 20 20  on-NULL or.***  
2ed80 20 20 20 20 20 20 20 46 20 69 73 20 6e 6f 6e 2d         F is non-
2ed90 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c  NULL and S and L
2eda0 20 61 72 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a   are NULL..**.**
2edb0 20 7b 48 31 36 31 32 31 7d 20 54 68 65 20 5b 73   {H16121} The [s
2edc0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2edd0 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69  nction(D,...)] i
2ede0 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 66  nterface shall f
2edf0 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20  ails with an.** 
2ee00 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 63           error c
2ee10 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42  ode of [SQLITE_B
2ee20 55 53 59 5d 20 69 66 20 74 68 65 72 65 20 65 78  USY] if there ex
2ee30 69 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  ist [prepared st
2ee40 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20  atements].**    
2ee50 20 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 64        associated
2ee60 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
2ee70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2ee80 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 34  D..**.** {H16124
2ee90 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2eea0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2eeb0 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  ,X,N,...)] inter
2eec0 66 61 63 65 20 73 68 61 6c 6c 20 66 61 69 6c 20  face shall fail 
2eed0 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  with.**         
2eee0 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 6f   an error code o
2eef0 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  f [SQLITE_ERROR]
2ef00 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 4e 20   if parameter N 
2ef10 69 73 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20  is less.**      
2ef20 20 20 20 20 74 68 61 6e 20 2d 31 20 6f 72 20 67      than -1 or g
2ef30 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 2e  reater than 127.
2ef40 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 37 7d 20  .**.** {H16127} 
2ef50 57 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  When N is non-ne
2ef60 67 61 74 69 76 65 2c 20 74 68 65 20 5b 73 71 6c  gative, the [sql
2ef70 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2ef80 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
2ef90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
2efa0 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 67  erface shall reg
2efb0 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 73 20  ister callbacks 
2efc0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f  to be invoked fo
2efd0 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
2efe0 20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a    SQL function.*
2eff0 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 64  *          named
2f000 20 58 20 77 68 65 6e 20 74 68 65 20 6e 75 6d 62   X when the numb
2f010 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2f020 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
2f030 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ion is.**       
2f040 20 20 20 65 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a     exactly N..**
2f050 0a 2a 2a 20 7b 48 31 36 31 33 30 7d 20 57 68 65  .** {H16130} Whe
2f060 6e 20 4e 20 69 73 20 2d 31 2c 20 74 68 65 20 5b  n N is -1, the [
2f070 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2f080 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e  unction(D,X,N,..
2f090 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
2f0a0 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
2f0b0 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
2f0c0 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ks to be invoked
2f0d0 20 66 6f 72 20 74 68 65 20 53 51 4c 0a 2a 2a 20   for the SQL.** 
2f0e0 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f           functio
2f0f0 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 61  n named X with a
2f100 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
2f110 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  uments..**.** {H
2f120 31 36 31 33 33 7d 20 57 68 65 6e 20 63 61 6c 6c  16133} When call
2f130 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  s to [sqlite3_cr
2f140 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2f150 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  X,N,...)].**    
2f160 20 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75        specify mu
2f170 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
2f180 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2f190 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a  me function X.**
2f1a0 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 77 68            and wh
2f1b0 65 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d 65 6e 74  en one implement
2f1c0 61 74 69 6f 6e 20 68 61 73 20 4e 3e 3d 30 20 61  ation has N>=0 a
2f1d0 6e 64 20 74 68 65 20 6f 74 68 65 72 20 68 61 73  nd the other has
2f1e0 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20 20 20 20   N=(-1).**      
2f1f0 20 20 20 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e      the implemen
2f200 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
2f210 6e 2d 7a 65 72 6f 20 4e 20 73 68 61 6c 6c 20 62  n-zero N shall b
2f220 65 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a  e preferred..**.
2f230 2a 2a 20 7b 48 31 36 31 33 36 7d 20 57 68 65 6e  ** {H16136} When
2f240 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
2f250 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2f260 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d  on(D,X,N,E,...)]
2f270 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70 65  .**          spe
2f280 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d  cify multiple im
2f290 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2f2a0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2f2b0 6f 6e 20 58 20 77 69 74 68 0a 2a 2a 20 20 20 20  on X with.**    
2f2c0 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 6e        the same n
2f2d0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2f2e0 74 73 20 4e 20 62 75 74 20 77 69 74 68 20 64 69  ts N but with di
2f2f0 66 66 65 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20  fferent.**      
2f300 20 20 20 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c      encodings E,
2f310 20 74 68 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d   then the implem
2f320 65 6e 74 61 74 69 6f 6e 20 77 68 65 72 65 20 45  entation where E
2f330 20 6d 61 74 63 68 65 73 20 74 68 65 0a 2a 2a 20   matches the.** 
2f340 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73           databas
2f350 65 20 65 6e 63 6f 64 69 6e 67 20 73 68 61 6c 6c  e encoding shall
2f360 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a   preferred..**.*
2f370 2a 20 7b 48 31 36 31 33 39 7d 20 46 6f 72 20 61  * {H16139} For a
2f380 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
2f390 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 65 64  function created
2f3a0 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
2f3b0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61     [sqlite3_crea
2f3c0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2f3d0 4e 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d 20 74 68  N,E,P,0,S,L)] th
2f3e0 65 20 66 69 6e 61 6c 69 7a 65 72 0a 2a 2a 20 20  e finalizer.**  
2f3f0 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e          function
2f400 20 4c 20 73 68 61 6c 6c 20 61 6c 77 61 79 73 20   L shall always 
2f410 62 65 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74  be invoked exact
2f420 6c 79 20 6f 6e 63 65 20 69 66 20 74 68 65 0a 2a  ly once if the.*
2f430 2a 20 20 20 20 20 20 20 20 20 20 73 74 65 70 20  *          step 
2f440 66 75 6e 63 74 69 6f 6e 20 53 20 69 73 20 63 61  function S is ca
2f450 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
2f460 20 74 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48   times..**.** {H
2f470 31 36 31 34 32 7d 20 57 68 65 6e 20 53 51 4c 69  16142} When SQLi
2f480 74 65 20 69 6e 76 6f 6b 65 73 20 65 69 74 68 65  te invokes eithe
2f490 72 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78  r the xFunc or x
2f4a0 53 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 6f 66  Step function of
2f4b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20  .**          an 
2f4c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2f4d0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2f4e0 20 6f 72 20 61 67 67 72 65 67 61 74 65 20 63 72   or aggregate cr
2f4f0 65 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  eated.**        
2f500 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 72    by [sqlite3_cr
2f510 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2f520 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   or [sqlite3_cre
2f530 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2f540 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ],.**          t
2f550 68 65 6e 20 74 68 65 20 61 72 72 61 79 20 6f 66  hen the array of
2f560 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2f570 20 6f 62 6a 65 63 74 73 20 70 61 73 73 65 64 20   objects passed 
2f580 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  as the.**       
2f590 20 20 20 74 68 69 72 64 20 70 61 72 61 6d 65 74     third paramet
2f5a0 65 72 20 73 68 61 6c 6c 20 62 65 20 5b 70 72 6f  er shall be [pro
2f5b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2f5c0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2f5d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
2f5e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
2f5f0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
2f600 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
2f610 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
2f620 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
2f630 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
2f640 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
2f650 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
2f660 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2f670 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2f680 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
2f690 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2f6a0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2f6b0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
2f6c0 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
2f6d0 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
2f6e0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f6f0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
2f700 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
2f710 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
2f720 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2f730 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2f740 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2f750 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2f760 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2f770 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2f780 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2f790 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2f7a0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2f7b0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2f7c0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2f7d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
2f7e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f7f0 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
2f800 73 20 7b 48 31 30 32 36 37 7d 20 3c 53 35 30 32  s {H10267} <S502
2f810 30 30 3e 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a  00> <H16100>.**.
2f820 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2f830 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
2f840 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
2f850 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
2f860 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
2f870 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
2f880 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
2f890 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
2f8a0 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
2f8b0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2f8c0 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
2f8d0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2f8e0 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
2f8f0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2f900 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
2f910 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
2f920 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
2f930 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
2f940 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
2f950 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2f960 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
2f970 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2f980 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
2f990 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
2f9a0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
2f9b0 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
2f9c0 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
2f9d0 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
2f9e0 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
2f9f0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
2fa00 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
2fa10 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
2fa20 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
2fa30 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
2fa40 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
2fa50 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
2fa60 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
2fa70 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
2fa80 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
2fa90 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
2faa0 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
2fab0 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
2fac0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
2fad0 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
2fae0 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
2faf0 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
2fb00 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
2fb10 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
2fb20 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64   you what they d
2fb30 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
2fb40 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
2fb50 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52  ATED.SQLITE_DEPR
2fb60 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2fb70 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
2fb80 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
2fb90 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  xt*);.SQLITE_DEP
2fba0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2fbb0 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
2fbc0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
2fbd0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2fbe0 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
2fbf0 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
2fc00 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
2fc10 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
2fc20 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2fc30 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
2fc40 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
2fc50 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2fc60 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
2fc70 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
2fc80 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
2fc90 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2fca0 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
2fcb0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2fcc0 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
2fcd0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
2fce0 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  t64);.#endif../*
2fcf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
2fd00 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63  taining SQL Func
2fd10 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56  tion Parameter V
2fd20 61 6c 75 65 73 20 7b 48 31 35 31 30 30 7d 20 3c  alues {H15100} <
2fd30 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
2fd40 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
2fd50 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
2fd60 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
2fd70 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
2fd80 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
2fd90 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
2fda0 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
2fdb0 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
2fdc0 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
2fdd0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
2fde0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75  e..**.** The xFu
2fdf0 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
2fe00 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
2fe10 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
2fe20 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
2fe30 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
2fe40 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2fe50 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
2fe60 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2fe70 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
2fe80 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
2fe90 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
2fea0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
2feb0 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34  egates..** The 4
2fec0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2fed0 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
2fee0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
2fef0 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
2ff00 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2ff10 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2ff20 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
2ff30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2ff40 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
2ff50 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2ff60 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
2ff70 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
2ff80 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
2ff90 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
2ffa0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
2ffb0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2ffc0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2ffd0 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
2ffe0 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
2fff0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
30000 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
30010 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
30020 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
30030 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
30040 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
30050 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
30060 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
30070 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  havior..**.** Th
30080 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
30090 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
300a0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
300b0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
300c0 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
300d0 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f  t that  these ro
300e0 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
300f0 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
30100 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
30110 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
30120 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
30130 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
30140 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
30150 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
30160 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
30170 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30180 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
30190 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36  xtracts a UTF-16
301a0 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
301b0 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
301c0 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
301d0 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a  machine.  The.**
301e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
301f0 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
30200 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30210 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
30220 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
30230 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
30240 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
30250 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
30260 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
30270 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
30280 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
30290 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
302a0 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
302b0 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
302c0 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
302d0 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
302e0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
302f0 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
30300 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
30310 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
30320 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
30330 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
30340 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
30350 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
30360 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
30370 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
30380 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
30390 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
303a0 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
303b0 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
303c0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
303d0 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
303e0 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
303f0 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
30400 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
30410 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
30420 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
30430 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
30440 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
30450 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
30460 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
30470 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
30480 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
30490 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
304a0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
304b0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
304c0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
304d0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
304e0 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
304f0 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
30500 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
30510 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
30520 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
30530 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
30540 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30550 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
30560 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30570 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  t16()]..**.** Th
30580 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
30590 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
305a0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
305b0 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
305c0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
305d0 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
305e0 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
305f0 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  eters..**.** INV
30600 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
30610 48 31 35 31 30 33 7d 20 54 68 65 20 5b 73 71 6c  H15103} The [sql
30620 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
30630 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
30640 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
30650 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
30660 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
30670 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
30680 20 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e 0a 2a   BLOB and then.*
30690 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
306a0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
306b0 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61  the converted va
306c0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  lue..**.** {H151
306d0 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  06} The [sqlite3
306e0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 56 29 5d  _value_bytes(V)]
306f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30700 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
30710 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74     number of byt
30720 65 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f  es in the BLOB o
30730 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73  r string (exclus
30740 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ive of the.**   
30750 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d         zero term
30760 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74  inator on the st
30770 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72  ring) that was r
30780 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
30790 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20  *          most 
307a0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
307b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
307c0 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  ob(V)] or.**    
307d0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76        [sqlite3_v
307e0 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a  alue_text(V)]..*
307f0 2a 0a 2a 2a 20 7b 48 31 35 31 30 39 7d 20 54 68  *.** {H15109} Th
30800 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
30810 5f 62 79 74 65 73 31 36 28 56 29 5d 20 69 6e 74  _bytes16(V)] int
30820 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
30830 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
30840 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
30850 6e 20 74 68 65 20 73 74 72 69 6e 67 20 28 65 78  n the string (ex
30860 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a  clusive of the.*
30870 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
30880 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68  terminator on th
30890 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77  e string) that w
308a0 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  as returned by t
308b0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  he.**          m
308c0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
308d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  to [sqlite3_valu
308e0 65 5f 74 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a  e_text16(V)],.**
308f0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
30900 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
30910 65 28 56 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  e(V)], or [sqlit
30920 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
30930 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  e(V)]..**.** {H1
30940 35 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  5112} The [sqlit
30950 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
30960 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
30970 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
30980 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
30990 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
309a0 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
309b0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
309c0 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20  value and.**    
309d0 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
309e0 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c  copy of that val
309f0 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31  ue..**.** {H1511
30a00 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
30a10 76 61 6c 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e  value_int(V)] in
30a20 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
30a30 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30a40 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
30a50 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
30a60 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  t V into a 64-bi
30a70 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
30a80 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
30a90 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77   returns the low
30aa0 65 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 68  er 32 bits of th
30ab0 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  at integer..**.*
30ac0 2a 20 7b 48 31 35 31 31 38 7d 20 54 68 65 20 5b  * {H15118} The [
30ad0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
30ae0 74 36 34 28 56 29 5d 20 69 6e 74 65 72 66 61 63  t64(V)] interfac
30af0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
30b00 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
30b10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30b20 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
30b30 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e  to a 64-bit sign
30b40 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a  ed integer and.*
30b50 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
30b60 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61  ns a copy of tha
30b70 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
30b80 20 7b 48 31 35 31 32 31 7d 20 54 68 65 20 5b 73   {H15121} The [s
30b90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30ba0 74 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(V)] interface 
30bb0 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
30bc0 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
30bd0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
30be0 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
30bf0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
30c00 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20  ed UTF-8.**     
30c10 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
30c20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
30c30 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
30c40 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 34 7d  ..**.** {H15124}
30c50 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
30c60 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 20 69  lue_text16(V)] i
30c70 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
30c80 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
30c90 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
30ca0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30cb0 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f  ct V into a zero
30cc0 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79  -terminated 2-by
30cd0 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
30ce0 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61  ligned UTF-16 na
30cf0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a  tive byte order.
30d00 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
30d10 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
30d20 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
30d30 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
30d40 48 31 35 31 32 37 7d 20 54 68 65 20 5b 73 71 6c  H15127} The [sql
30d50 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
30d60 36 62 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  6be(V)] interfac
30d70 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
30d80 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
30d90 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30da0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
30db0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
30dc0 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20  ated 2-byte.**  
30dd0 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20          aligned 
30de0 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61  UTF-16 big-endia
30df0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  n.**          st
30e00 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
30e10 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
30e20 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
30e30 20 7b 48 31 35 31 33 30 7d 20 54 68 65 20 5b 73   {H15130} The [s
30e40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30e50 74 31 36 6c 65 28 56 29 5d 20 69 6e 74 65 72 66  t16le(V)] interf
30e60 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
30e70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
30e80 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30e90 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
30ea0 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
30eb0 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a  inated 2-byte.**
30ec0 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65            aligne
30ed0 64 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d  d UTF-16 little-
30ee0 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20  endian.**       
30ef0 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
30f00 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
30f10 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
30f20 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 33 7d 20 54  **.** {H15133} T
30f30 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
30f40 65 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72  e_type(V)] inter
30f50 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
30f60 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20           one of 
30f70 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b  [SQLITE_NULL], [
30f80 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
30f90 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
30fa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
30fb0 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b  LITE_TEXT], or [
30fc0 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20  SQLITE_BLOB] as 
30fd0 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a  appropriate for.
30fe0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
30ff0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
31000 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20  object V..**.** 
31010 7b 48 31 35 31 33 36 7d 20 54 68 65 20 5b 73 71  {H15136} The [sq
31020 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
31030 72 69 63 5f 74 79 70 65 28 56 29 5d 20 69 6e 74  ric_type(V)] int
31040 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 0a  erface converts.
31050 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
31060 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
31070 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
31080 20 56 20 69 6e 74 6f 20 65 69 74 68 65 72 20 61   V into either a
31090 6e 20 69 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20  n integer or.** 
310a0 20 20 20 20 20 20 20 20 20 61 20 66 6c 6f 61 74           a float
310b0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
310c0 69 66 20 69 74 20 63 61 6e 20 64 6f 20 73 6f 20  if it can do so 
310d0 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a  without loss of.
310e0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f  **          info
310f0 72 6d 61 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74  rmation, and ret
31100 75 72 6e 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  urns one of [SQL
31110 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20  ITE_NULL],.**   
31120 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49         [SQLITE_I
31130 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45  NTEGER], [SQLITE
31140 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
31150 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20  _TEXT], or.**   
31160 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 42         [SQLITE_B
31170 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69  LOB] as appropri
31180 61 74 65 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  ate for the.**  
31190 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
311a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
311b0 5d 20 6f 62 6a 65 63 74 20 56 20 61 66 74 65 72  ] object V after
311c0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
311d0 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73  attempt..*/.cons
311e0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
311f0 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
31200 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
31210 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
31220 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
31230 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
31240 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
31250 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31260 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
31270 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
31280 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
31290 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
312a0 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
312b0 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
312c0 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
312d0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
312e0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
312f0 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
31300 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
31310 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31320 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
31330 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
31340 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31350 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
31360 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
31370 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
31380 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
31390 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
313a0 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
313b0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
313c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
313d0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
313e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
313f0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
31400 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31410 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31420 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
31430 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
31440 74 65 78 74 20 7b 48 31 36 32 31 30 7d 20 3c 53  text {H16210} <S
31450 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
31460 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31470 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
31480 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
31490 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  his routine to a
314a0 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72  llocate.** a str
314b0 75 63 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69  ucture for stori
314c0 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a  ng their state..
314d0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
314e0 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
314f0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31500 78 74 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  xt() routine is 
31510 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a 2a 2a 20  called for a.** 
31520 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
31530 67 61 74 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c  gate, SQLite all
31540 6f 63 61 74 65 73 20 6e 42 79 74 65 73 20 6f 66  ocates nBytes of
31550 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
31560 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f  out that.** memo
31570 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
31580 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e  a pointer to it.
31590 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73   On second and s
315a0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
315b0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
315c0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
315d0 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
315e0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
315f0 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 68 65 20  n index,.** the 
31600 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
31610 65 74 75 72 6e 65 64 2e 20 54 68 65 20 69 6d 70  eturned. The imp
31620 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
31630 68 65 20 61 67 67 72 65 67 61 74 65 20 63 61 6e  he aggregate can
31640 20 75 73 65 0a 2a 2a 20 74 68 65 20 72 65 74 75   use.** the retu
31650 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20 61  rned buffer to a
31660 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a  ccumulate data..
31670 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 61 75 74  **.** SQLite aut
31680 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
31690 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   the allocated b
316a0 75 66 66 65 72 20 77 68 65 6e 20 74 68 65 20 61  uffer when the a
316b0 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 72  ggregate.** quer
316c0 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
316d0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
316e0 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
316f0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
31700 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
31710 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
31720 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
31730 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
31740 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
31750 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
31760 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
31770 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  s the aggregate 
31780 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
31790 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
317a0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
317b0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
317c0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
317d0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
317e0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
317f0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ng..**.** INVARI
31800 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ANTS:.**.** {H16
31810 32 31 31 7d 20 54 68 65 20 66 69 72 73 74 20 69  211} The first i
31820 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
31830 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
31840 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f  context(C,N)] fo
31850 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  r.**          a 
31860 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61  particular insta
31870 6e 63 65 20 6f 66 20 61 6e 20 61 67 67 72 65 67  nce of an aggreg
31880 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 28 66 6f  ate function (fo
31890 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
318a0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65  *          conte
318b0 78 74 20 43 29 20 63 61 75 73 65 73 20 53 51 4c  xt C) causes SQL
318c0 69 74 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ite to allocate 
318d0 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
318e0 79 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  y,.**          z
318f0 65 72 6f 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  ero that memory,
31900 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f   and return a po
31910 69 6e 74 65 72 20 74 6f 20 74 68 65 20 61 6c 6c  inter to the all
31920 6f 63 61 74 65 64 20 6d 65 6d 6f 72 79 2e 0a 2a  ocated memory..*
31930 2a 0a 2a 2a 20 7b 48 31 36 32 31 33 7d 20 49 66  *.** {H16213} If
31940 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
31950 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
31960 73 20 64 75 72 69 6e 67 0a 2a 2a 20 20 20 20 20  s during.**     
31970 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67       [sqlite3_ag
31980 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31990 43 2c 4e 29 5d 20 74 68 65 6e 20 74 68 65 20 66  C,N)] then the f
319a0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
319b0 30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 35  0..**.** {H16215
319c0 7d 20 53 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  } Second and sub
319d0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
319e0 6f 6e 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ons of.**       
319f0 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72     [sqlite3_aggr
31a00 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
31a10 4e 29 5d 20 66 6f 72 20 74 68 65 20 73 61 6d 65  N)] for the same
31a20 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
31a30 20 43 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69   C.**          i
31a40 67 6e 6f 72 65 20 74 68 65 20 4e 20 70 61 72 61  gnore the N para
31a50 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
31a60 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
31a70 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
31a80 20 20 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f     block of memo
31a90 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ry returned by t
31aa0 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74  he first invocat
31ab0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  ion..**.** {H162
31ac0 31 37 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  17} The memory a
31ad0 6c 6c 6f 63 61 74 65 64 20 62 79 20 5b 73 71 6c  llocated by [sql
31ae0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
31af0 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 69 73 0a  ontext(C,N)] is.
31b00 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f  **          auto
31b10 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20  matically freed 
31b20 6f 6e 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  on the next call
31b30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
31b40 65 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  et()].**        
31b50 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69    or [sqlite3_fi
31b60 6e 61 6c 69 7a 65 28 29 5d 20 66 6f 72 20 74 68  nalize()] for th
31b70 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
31b80 65 6d 65 6e 74 5d 20 63 6f 6e 74 61 69 6e 69 6e  ement] containin
31b90 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  g.**          th
31ba0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
31bb0 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20  tion associated 
31bc0 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a  with context C..
31bd0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
31be0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31bf0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
31c00 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
31c10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31c20 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
31c30 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32   Functions {H162
31c40 34 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  40} <S20200>.**.
31c50 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
31c60 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
31c70 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
31c80 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
31c90 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
31ca0 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
31cb0 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
31cc0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
31cd0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
31ce0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
31cf0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
31d00 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
31d10 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
31d20 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
31d30 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
31d40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
31d50 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b  ined function. {
31d60 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  END}.**.** This 
31d70 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
31d80 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
31d90 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
31da0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
31db0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
31dc0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
31dd0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ing..**.** INVAR
31de0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
31df0 36 32 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  6243} The [sqlit
31e00 65 33 5f 75 73 65 72 5f 64 61 74 61 28 43 29 5d  e3_user_data(C)]
31e10 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
31e20 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
31e30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 50 20 70  .**          P p
31e40 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 20  ointer from the 
31e50 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
31e60 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
31e70 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20  ,P,F,S,L)].**   
31e80 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
31e90 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
31ea0 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  on16(D,X,N,E,P,F
31eb0 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74  ,S,L)] call that
31ec0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
31ed0 69 73 74 65 72 65 64 20 74 68 65 20 53 51 4c 20  istered the SQL 
31ee0 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61  function associa
31ef0 74 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  ted with [sqlite
31f00 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f  3_context] C..*/
31f10 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
31f20 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33  ser_data(sqlite3
31f30 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
31f40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
31f50 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
31f60 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b   For Functions {
31f70 48 31 36 32 35 30 7d 20 3c 53 36 30 36 30 30 3e  H16250} <S60600>
31f80 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20200>.**.** T
31f90 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
31fa0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
31fb0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
31fc0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
31fd0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
31fe0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
31ff0 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
32000 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
32010 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
32020 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
32030 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
32040 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32050 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
32060 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
32070 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
32080 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
32090 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
320a0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
320b0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 35 33 7d 20  .**.** {H16253} 
320c0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
320d0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 43  text_db_handle(C
320e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
320f0 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  urns a copy of t
32100 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44  he.**          D
32110 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68   pointer from th
32120 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
32130 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
32140 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20  ,E,P,F,S,L)].** 
32150 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
32160 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
32170 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50  tion16(D,X,N,E,P
32180 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68  ,F,S,L)] call th
32190 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  at.**          r
321a0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 53 51  egistered the SQ
321b0 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63  L function assoc
321c0 69 61 74 65 64 20 77 69 74 68 20 5b 73 71 6c 69  iated with [sqli
321d0 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a  te3_context] C..
321e0 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
321f0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
32200 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
32210 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
32220 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
32230 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
32240 61 20 7b 48 31 36 32 37 30 7d 20 3c 53 32 30 32  a {H16270} <S202
32250 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  00>.**.** The fo
32260 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63  llowing two func
32270 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65  tions may be use
32280 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20  d by scalar SQL 
32290 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
322a0 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
322b0 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
322c0 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
322d0 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
322e0 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
322f0 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
32300 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
32310 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
32320 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
32330 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
32340 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
32350 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
32360 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
32370 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a  erved. This may.
32380 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20  ** be used, for 
32390 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20  example, to add 
323a0 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
323b0 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63  sion matching sc
323c0 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  alar.** function
323d0 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
323e0 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
323f0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
32400 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a   is stored as.**
32410 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
32420 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51  ated with the SQ
32430 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  L value passed a
32440 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  s the regular ex
32450 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74  pression.** patt
32460 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c  ern.  The compil
32470 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  ed regular expre
32480 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75  ssion can be reu
32490 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a  sed on multiple.
324a0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
324b0 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
324c0 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20  ion so that the 
324d0 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e  original pattern
324e0 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20   string.** does 
324f0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72  not need to be r
32500 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63  ecompiled on eac
32510 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  h invocation..**
32520 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
32530 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
32540 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
32550 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
32560 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
32570 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
32580 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
32590 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
325a0 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
325b0 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
325c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
325d0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
325e0 2e 20 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61  . If no metadata
325f0 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a   has been ever.*
32600 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74  * been set for t
32610 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20  he Nth argument 
32620 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c  of the function,
32630 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65   or if the corre
32640 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63  sponding.** func
32650 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68  tion parameter h
32660 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65  as changed since
32670 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77   the meta-data w
32680 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20  as set,.** then 
32690 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
326a0 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20  ata() returns a 
326b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
326c0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
326d0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
326e0 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68  terface saves th
326f0 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f  e metadata.** po
32700 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20  inted to by its 
32710 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  3rd parameter as
32720 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f   the metadata fo
32730 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
32740 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
32750 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32760 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62  d function.  Sub
32770 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
32780 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
32790 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20  auxdata() might 
327a0 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61  return this data
327b0 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e  , if it has.** n
327c0 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65  ot been destroye
327d0 64 2e 0a 2a 2a 20 49 66 20 69 74 20 69 73 20 6e  d..** If it is n
327e0 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
327f0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
32800 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75  destructor.** fu
32810 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20  nction given by 
32820 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
32830 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  r to sqlite3_set
32840 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a  _auxdata() on.**
32850 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68   the metadata wh
32860 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
32870 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
32880 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a  rameter changes.
32890 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53  ** or when the S
328a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
328b0 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65  pletes, whicheve
328c0 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a  r comes first..*
328d0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66  *.** SQLite is f
328e0 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20  ree to call the 
328f0 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64  destructor and d
32900 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20  rop metadata on 
32910 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  any.** parameter
32920 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e   of any function
32930 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 54   at any time.  T
32940 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65  he only guarante
32950 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  e is that.** the
32960 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c   destructor will
32970 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
32980 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  e the metadata i
32990 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a  s dropped..**.**
329a0 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65   In practice, me
329b0 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
329c0 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
329d0 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
329e0 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
329f0 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
32a00 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
32a10 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
32a20 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
32a30 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c   and SQL variabl
32a40 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es..**.** These 
32a50 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
32a60 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
32a70 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
32a80 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
32a90 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
32aa0 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ning..**.** INVA
32ab0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
32ac0 31 36 32 37 32 7d 20 54 68 65 20 5b 73 71 6c 69  16272} The [sqli
32ad0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
32ae0 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,N)] interface 
32af0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
32b00 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  r.**          to
32b10 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
32b20 61 74 65 64 20 77 69 74 68 20 74 68 65 20 4e 74  ated with the Nt
32b30 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  h parameter of t
32b40 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a  he SQL function.
32b50 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 6f 73  **          whos
32b60 65 20 63 6f 6e 74 65 78 74 20 69 73 20 43 2c 20  e context is C, 
32b70 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65  or NULL if there
32b80 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 20   is no metadata 
32b90 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20  associated.**   
32ba0 20 20 20 20 20 20 20 77 69 74 68 20 74 68 61 74         with that
32bb0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
32bc0 2a 20 7b 48 31 36 32 37 34 7d 20 54 68 65 20 5b  * {H16274} The [
32bd0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
32be0 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 6e  ata(C,N,P,D)] in
32bf0 74 65 72 66 61 63 65 20 61 73 73 69 67 6e 73 20  terface assigns 
32c00 61 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20 20  a metadata.**   
32c10 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 50         pointer P
32c20 20 74 6f 20 74 68 65 20 4e 74 68 20 70 61 72 61   to the Nth para
32c30 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c  meter of the SQL
32c40 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 63   function with c
32c50 6f 6e 74 65 78 74 20 43 2e 0a 2a 2a 0a 2a 2a 20  ontext C..**.** 
32c60 7b 48 31 36 32 37 36 7d 20 53 51 4c 69 74 65 20  {H16276} SQLite 
32c70 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
32c80 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74  destructor D wit
32c90 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  h a single argum
32ca0 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ent.**          
32cb0 77 68 69 63 68 20 69 73 20 74 68 65 20 6d 65 74  which is the met
32cc0 61 64 61 74 61 20 70 6f 69 6e 74 65 72 20 50 20  adata pointer P 
32cd0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
32ce0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
32cf0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
32d00 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 77  data(C,N,P,D)] w
32d10 68 65 6e 20 53 51 4c 69 74 65 20 63 65 61 73 65  hen SQLite cease
32d20 73 20 74 6f 20 68 6f 6c 64 0a 2a 2a 20 20 20 20  s to hold.**    
32d30 20 20 20 20 20 20 74 68 65 20 6d 65 74 61 64 61        the metada
32d40 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37  ta..**.** {H1627
32d50 37 7d 20 53 51 4c 69 74 65 20 63 65 61 73 65 73  7} SQLite ceases
32d60 20 74 6f 20 68 6f 6c 64 20 6d 65 74 61 64 61 74   to hold metadat
32d70 61 20 66 6f 72 20 61 6e 20 53 51 4c 20 66 75 6e  a for an SQL fun
32d80 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a  ction parameter.
32d90 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e  **          when
32da0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
32db0 61 74 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  at parameter cha
32dc0 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  nges..**.** {H16
32dd0 32 37 38 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74  278} When [sqlit
32de0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
32df0 2c 4e 2c 50 2c 44 29 5d 20 69 73 20 69 6e 76 6f  ,N,P,D)] is invo
32e00 6b 65 64 2c 20 74 68 65 20 64 65 73 74 72 75 63  ked, the destruc
32e10 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tor.**          
32e20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 6e  is called for an
32e30 79 20 70 72 69 6f 72 20 6d 65 74 61 64 61 74 61  y prior metadata
32e40 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
32e50 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
32e60 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  on.**          c
32e70 6f 6e 74 65 78 74 20 43 20 61 6e 64 20 70 61 72  ontext C and par
32e80 61 6d 65 74 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20  ameter N..**.** 
32e90 7b 48 31 36 32 37 39 7d 20 53 51 4c 69 74 65 20  {H16279} SQLite 
32ea0 77 69 6c 6c 20 63 61 6c 6c 20 64 65 73 74 72 75  will call destru
32eb0 63 74 6f 72 73 20 66 6f 72 20 61 6e 79 20 6d 65  ctors for any me
32ec0 74 61 64 61 74 61 20 69 74 20 69 73 20 68 6f 6c  tadata it is hol
32ed0 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ding.**         
32ee0 20 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72   in a particular
32ef0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32f00 6d 65 6e 74 5d 20 53 20 77 68 65 6e 20 65 69 74  ment] S when eit
32f10 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
32f20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
32f30 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
32f40 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63  inalize(S)] is c
32f50 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  alled..*/.void *
32f60 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
32f70 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
32f80 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
32f90 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
32fa0 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
32fb0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
32fc0 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
32fd0 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
32fe0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
32ff0 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
33000 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
33010 20 42 65 68 61 76 69 6f 72 20 7b 48 31 30 32 38   Behavior {H1028
33020 30 7d 20 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S30100>.**.*
33030 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
33040 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
33050 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
33060 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
33070 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
33080 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
33090 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
330a0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
330b0 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73 74 72  ].  If the destr
330c0 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
330d0 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
330e0 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
330f0 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
33100 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
33110 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
33120 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
33130 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
33140 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
33150 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
33160 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
33170 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
33180 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
33190 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
331a0 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
331b0 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
331c0 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
331d0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
331e0 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
331f0 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
33200 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
33210 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
33220 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
33230 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
33240 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
33250 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b  ilers.  See tick
33260 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70  et #2191..*/.typ
33270 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
33280 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
33290 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
332a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
332b0 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
332c0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
332d0 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
332e0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
332f0 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
33300 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
33310 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
33320 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
33330 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
33340 74 69 6f 6e 20 7b 48 31 36 34 30 30 7d 20 3c 53  tion {H16400} <S
33350 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
33360 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
33370 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
33380 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
33390 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
333a0 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
333b0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
333c0 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
333d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
333e0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
333f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
33400 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
33410 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
33420 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
33430 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
33440 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
33450 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
33460 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
33470 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
33480 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
33490 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
334a0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
334b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
334c0 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
334d0 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
334e0 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
334f0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
33500 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
33510 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
33520 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74  esult_blob() int
33530 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
33540 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
33550 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
33560 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
33570 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68  o be the BLOB wh
33580 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70  ose content is p
33590 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20  ointed.** to by 
335a0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
335b0 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69  eter and which i
335c0 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77  s N bytes long w
335d0 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
335e0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
335f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
33600 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
33610 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73  lob() interfaces
33620 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
33630 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
33640 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
33650 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42  nction to be a B
33660 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
33670 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73  ll zero.** bytes
33680 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
33690 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73  size, where N is
336a0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
336b0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
336c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
336d0 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
336e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
336f0 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
33700 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
33710 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
33720 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f  tion to be a flo
33730 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
33740 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
33750 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  y its 2nd argume
33760 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  nt..**.** The sq
33770 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33780 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
33790 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
337a0 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
337b0 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
337c0 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
337d0 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
337e0 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69  ception..** SQLi
337f0 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
33800 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
33810 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
33820 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
33830 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
33840 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
33850 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
33860 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
33870 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
33880 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65   SQLite interpre
33890 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ts the error.** 
338a0 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66  message string f
338b0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
338c0 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54  lt_error() as UT
338d0 46 2d 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69  F-8. SQLite.** i
338e0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74  nterprets the st
338f0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
33900 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
33910 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  () as UTF-16 in 
33920 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f  native.** byte o
33930 72 64 65 72 2e 20 20 49 66 20 74 68 65 20 74 68  rder.  If the th
33940 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
33950 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33960 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
33970 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33980 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69  or16() is negati
33990 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
339a0 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f  akes as the erro
339b0 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c  r.** message all
339c0 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68   text up through
339d0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
339e0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66  character..** If
339f0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
33a00 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
33a10 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
33a20 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
33a30 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
33a40 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
33a50 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
33a60 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
33a70 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
33a80 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
33a90 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
33aa0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
33ab0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
33ac0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
33ad0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
33ae0 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72  t_error16().** r
33af0 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70  outines make a p
33b00 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
33b10 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
33b20 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20   text before.** 
33b30 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65  they return.  He
33b40 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  nce, the calling
33b50 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65   function can de
33b60 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d  allocate or.** m
33b70 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61  odify the text a
33b80 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e  fter they return
33b90 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
33ba0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
33bb0 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
33bc0 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67  ) function chang
33bd0 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  es the error cod
33be0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
33bf0 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73   SQLite as a res
33c00 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ult of an error 
33c10 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20  in a function.  
33c20 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
33c30 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
33c40 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
33c50 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
33c60 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
33c70 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
33c80 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
33c90 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
33ca0 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
33cb0 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
33cc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
33cd0 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69  te3_result_toobi
33ce0 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
33cf0 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
33d00 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a  hrow an error.**
33d10 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
33d20 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
33d30 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20  B is to long to 
33d40 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
33d50 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
33d60 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ult_nomem() inte
33d70 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
33d80 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
33d90 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
33da0 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
33db0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
33dc0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  led..**.** The s
33dd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
33de0 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
33df0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
33e00 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
33e10 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33e20 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
33e30 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
33e40 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
33e50 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
33e60 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
33e70 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
33e80 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
33e90 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
33ea0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
33eb0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
33ec0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33ed0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
33ee0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
33ef0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
33f00 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
33f10 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
33f20 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
33f30 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  _null() interfac
33f40 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
33f50 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
33f60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
33f70 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
33f80 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
33f90 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
33fa0 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
33fb0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
33fc0 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  6(),.** sqlite3_
33fd0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
33fe0 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
33ff0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
34000 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
34010 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
34020 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
34030 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
34040 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
34050 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
34060 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
34070 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
34080 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
34090 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
340a0 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
340b0 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
340c0 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
340d0 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74  ely..** SQLite t
340e0 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65  akes the text re
340f0 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70  sult from the ap
34100 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a  plication from.*
34110 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  * the 2nd parame
34120 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ter of the sqlit
34130 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
34140 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49  interfaces..** I
34150 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
34160 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
34170 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
34180 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
34190 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
341a0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73  SQLite takes res
341b0 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68  ult text from th
341c0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  e 2nd parameter.
341d0 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  ** through the f
341e0 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
341f0 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33  ter..** If the 3
34200 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
34210 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
34220 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
34230 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65  ces.** is non-ne
34240 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20  gative, then as 
34250 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20  many bytes (not 
34260 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74  characters) of t
34270 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74  he text.** point
34280 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64  ed to by the 2nd
34290 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74   parameter are t
342a0 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c  aken as the appl
342b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a  ication-defined.
342c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75  ** function resu
342d0 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74  lt..** If the 4t
342e0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
342f0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34300 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
34310 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
34320 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
34330 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
34340 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
34350 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
34360 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
34370 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
34380 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
34390 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
343a0 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
343b0 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
343c0 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72  * If the 4th par
343d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
343e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
343f0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72  t* interfaces or
34400 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
34410 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
34420 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
34430 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
34440 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
34450 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
34460 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
34470 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
34480 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
34490 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
344a0 20 69 74 20 6f 72 20 63 61 6c 6c 20 61 20 64 65   it or call a de
344b0 73 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69 74  structor when it
344c0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
344d0 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
344e0 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70  .** If the 4th p
344f0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
34500 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34510 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
34520 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
34530 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
34540 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
34550 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
34560 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
34570 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
34580 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
34590 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
345a0 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
345b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
345c0 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
345d0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ns..**.** The sq
345e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
345f0 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ue() interface s
34600 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ets the result o
34610 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
34620 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
34630 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f  ction to be a co
34640 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f  py the.** [unpro
34650 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
34660 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65  alue] object spe
34670 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e  cified by the 2n
34680 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
34690 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
346a0 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
346b0 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
346c0 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
346d0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
346e0 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
346f0 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
34700 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
34710 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
34720 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
34730 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
34740 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
34750 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
34760 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f   harm..** A [pro
34770 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
34780 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79  alue] object may
34790 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20   always be used 
347a0 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70  where an.** [unp
347b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
347c0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69  _value] object i
347d0 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65  s required, so e
347e0 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66  ither.** kind of
347f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
34800 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75   object can be u
34810 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e  sed with this in
34820 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
34830 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
34840 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
34850 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66   within the diff
34860 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20  erent thread.** 
34870 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e  than the one con
34880 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c  taining the appl
34890 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
348a0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65  function that re
348b0 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73  ceived.** the [s
348c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
348d0 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73  pointer, the res
348e0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
348f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
34900 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ANTS:.**.** {H16
34910 34 30 33 7d 20 54 68 65 20 64 65 66 61 75 6c 74  403} The default
34920 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
34930 6f 6d 20 61 6e 79 20 53 51 4c 20 66 75 6e 63 74  om any SQL funct
34940 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ion is NULL..**.
34950 2a 2a 20 7b 48 31 36 34 30 36 7d 20 54 68 65 20  ** {H16406} The 
34960 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
34970 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  blob(C,V,N,D)] i
34980 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
34990 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
349a0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
349b0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
349c0 65 20 61 20 42 4c 4f 42 20 74 68 61 74 20 69 73  e a BLOB that is
349d0 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20   N bytes.**     
349e0 20 20 20 20 20 69 6e 20 6c 65 6e 67 74 68 20 61       in length a
349f0 6e 64 20 77 69 74 68 20 63 6f 6e 74 65 6e 74 20  nd with content 
34a00 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2e  pointed to by V.
34a10 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 39 7d 20  .**.** {H16409} 
34a20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
34a30 75 6c 74 5f 64 6f 75 62 6c 65 28 43 2c 56 29 5d  ult_double(C,V)]
34a40 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
34a50 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
34a60 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
34a70 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
34a80 20 62 65 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   be the floating
34a90 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 56 2e 0a   point value V..
34aa0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 32 7d 20 54  **.** {H16412} T
34ab0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
34ac0 6c 74 5f 65 72 72 6f 72 28 43 2c 56 2c 4e 29 5d  lt_error(C,V,N)]
34ad0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
34ae0 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a  es the return.**
34af0 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
34b00 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
34b10 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e   be an exception
34b20 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65   with error code
34b30 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
34b40 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20  LITE_ERROR] and 
34b50 61 20 55 54 46 2d 38 20 65 72 72 6f 72 20 6d 65  a UTF-8 error me
34b60 73 73 61 67 65 20 63 6f 70 69 65 64 20 66 72 6f  ssage copied fro
34b70 6d 20 56 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  m V up to the.**
34b80 20 20 20 20 20 20 20 20 20 20 66 69 72 73 74 20            first 
34b90 7a 65 72 6f 20 62 79 74 65 20 6f 72 20 75 6e 74  zero byte or unt
34ba0 69 6c 20 4e 20 62 79 74 65 73 20 61 72 65 20 72  il N bytes are r
34bb0 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69  ead if N is posi
34bc0 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  tive..**.** {H16
34bd0 34 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  415} The [sqlite
34be0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
34bf0 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61  (C,V,N)] interfa
34c00 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
34c10 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
34c20 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74    value of funct
34c30 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65  ion C to be an e
34c40 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72  xception with er
34c50 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20  ror code.**     
34c60 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
34c70 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 2d 31 36  OR] and a UTF-16
34c80 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
34c90 65 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  er error message
34ca0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 70  .**          cop
34cb0 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f  ied from V up to
34cc0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
34cd0 74 65 72 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e  terminator or un
34ce0 74 69 6c 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20  til N bytes.**  
34cf0 20 20 20 20 20 20 20 20 61 72 65 20 72 65 61 64          are read
34d00 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76   if N is positiv
34d10 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 38  e..**.** {H16418
34d20 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
34d30 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
34d40 69 67 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  ig(C)] interface
34d50 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
34d60 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
34d70 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e  value of the fun
34d80 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
34d90 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
34da0 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
34db0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54         [SQLITE_T
34dc0 4f 4f 42 49 47 5d 20 61 6e 64 20 61 6e 20 61 70  OOBIG] and an ap
34dd0 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20  propriate error 
34de0 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b  message..**.** {
34df0 48 31 36 34 32 31 7d 20 54 68 65 20 5b 73 71 6c  H16421} The [sql
34e00 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34e10 72 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65  r_nomem(C)] inte
34e20 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
34e30 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
34e40 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
34e50 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  e function C to 
34e60 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
34e70 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a  with error code.
34e80 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
34e90 49 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61  ITE_NOMEM] and a
34ea0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72  n appropriate er
34eb0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
34ec0 2a 2a 20 7b 48 31 36 34 32 34 7d 20 54 68 65 20  ** {H16424} The 
34ed0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
34ee0 65 72 72 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d  error_code(C,E)]
34ef0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
34f00 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a  es the return.**
34f10 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
34f20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
34f30 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70  C to be an excep
34f40 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20  tion with error 
34f50 63 6f 64 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20  code E..**      
34f60 20 20 20 20 54 68 65 20 65 72 72 6f 72 20 6d 65      The error me
34f70 73 73 61 67 65 20 74 65 78 74 20 69 73 20 75 6e  ssage text is un
34f80 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  changed..**.** {
34f90 48 31 36 34 32 37 7d 20 54 68 65 20 5b 73 71 6c  H16427} The [sql
34fa0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
34fb0 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,V)] interface 
34fc0 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
34fd0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
34fe0 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
34ff0 20 43 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d   C to be the 32-
35000 62 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75  bit integer valu
35010 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  e V..**.** {H164
35020 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  30} The [sqlite3
35030 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c  _result_int64(C,
35040 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  V)] interface ch
35050 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
35060 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
35070 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
35080 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
35090 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20  t integer value 
350a0 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 33  V..**.** {H16433
350b0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
350c0 65 73 75 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69  esult_null(C)] i
350d0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
350e0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
350f0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
35100 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
35110 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  e NULL..**.** {H
35120 31 36 34 33 36 7d 20 54 68 65 20 5b 73 71 6c 69  16436} The [sqli
35130 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
35140 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
35150 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
35160 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
35170 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
35180 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
35190 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
351a0 20 20 20 20 20 20 20 20 20 20 56 20 75 70 20 74            V up t
351b0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
351c0 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76   if N is negativ
351d0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  e.**          or
351e0 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74   the first N byt
351f0 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20  es of V if N is 
35200 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a  non-negative..**
35210 0a 2a 2a 20 7b 48 31 36 34 33 39 7d 20 54 68 65  .** {H16439} The
35220 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
35230 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29  _text16(C,V,N,D)
35240 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
35250 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
35260 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
35270 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
35280 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31 36 20  o be the UTF-16 
35290 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
352a0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  r.**          st
352b0 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65  ring V up to the
352c0 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
352d0 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20   is negative.** 
352e0 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
352f0 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66  first N bytes of
35300 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e   V if N is non-n
35310 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
35320 48 31 36 34 34 32 7d 20 54 68 65 20 5b 73 71 6c  H16442} The [sql
35330 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35340 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  16be(C,V,N,D)] i
35350 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
35360 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
35370 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
35380 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
35390 65 20 74 68 65 20 55 54 46 2d 31 36 20 62 69 67  e the UTF-16 big
353a0 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20  -endian.**      
353b0 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20      string V up 
353c0 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
353d0 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69  o if N is negati
353e0 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ve.**          o
353f0 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79  r the first N by
35400 74 65 73 20 6f 72 20 56 20 69 66 20 4e 20 69 73  tes or V if N is
35410 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
35420 2a 0a 2a 2a 20 7b 48 31 36 34 34 35 7d 20 54 68  *.** {H16445} Th
35430 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
35440 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e  t_text16le(C,V,N
35450 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
35460 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
35470 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
35480 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
35490 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d  C to be the UTF-
354a0 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  16 little-endian
354b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
354c0 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20  ing V up to the 
354d0 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20  first zero if N 
354e0 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20  is negative.**  
354f0 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66          or the f
35500 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20  irst N bytes of 
35510 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  V if N is non-ne
35520 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  gative..**.** {H
35530 31 36 34 34 38 7d 20 54 68 65 20 5b 73 71 6c 69  16448} The [sqli
35540 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
35550 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,V)] interface
35560 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
35570 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
35580 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
35590 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 5b 75  n C to be the [u
355a0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
355b0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 20 20 20  e3_value].**    
355c0 20 20 20 20 20 20 6f 62 6a 65 63 74 20 56 2e 0a        object V..
355d0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 31 7d 20 54  **.** {H16451} T
355e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
355f0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29  lt_zeroblob(C,N)
35600 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
35610 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
35620 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
35630 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
35640 6f 20 62 65 20 61 6e 20 4e 2d 62 79 74 65 20 42  o be an N-byte B
35650 4c 4f 42 20 6f 66 20 61 6c 6c 20 7a 65 72 6f 73  LOB of all zeros
35660 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 34 7d  ..**.** {H16454}
35670 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
35680 73 75 6c 74 5f 65 72 72 6f 72 28 29 5d 20 61 6e  sult_error()] an
35690 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
356a0 74 5f 65 72 72 6f 72 31 36 28 29 5d 0a 2a 2a 20  t_error16()].** 
356b0 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
356c0 63 65 73 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  ces make a copy 
356d0 6f 66 20 74 68 65 69 72 20 65 72 72 6f 72 20 6d  of their error m
356e0 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 62  essage strings b
356f0 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20  efore.**        
35700 20 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a    returning..**.
35710 2a 2a 20 7b 48 31 36 34 35 37 7d 20 49 66 20 74  ** {H16457} If t
35720 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20  he D destructor 
35730 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
35740 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
35750 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  b(C,V,N,D)],.** 
35760 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
35770 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c  3_result_text(C,
35780 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65  V,N,D)], [sqlite
35790 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
357a0 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
357b0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
357c0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
357d0 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  C,V,N,D)], or.**
357e0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
357f0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
35800 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20  le(C,V,N,D)] is 
35810 74 68 65 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51  the constant [SQ
35820 4c 49 54 45 5f 53 54 41 54 49 43 5d 0a 2a 2a 20  LITE_STATIC].** 
35830 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 6e 6f           then no
35840 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 65   destructor is e
35850 76 65 72 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68  ver called on th
35860 65 20 70 6f 69 6e 74 65 72 20 56 20 61 6e 64 20  e pointer V and 
35870 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20 20  SQLite.**       
35880 20 20 20 61 73 73 75 6d 65 73 20 74 68 61 74 20     assumes that 
35890 56 20 69 73 20 69 6d 6d 75 74 61 62 6c 65 2e 0a  V is immutable..
358a0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 30 7d 20 49  **.** {H16460} I
358b0 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74  f the D destruct
358c0 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  or parameter to 
358d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
358e0 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a  blob(C,V,N,D)],.
358f0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
35900 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35910 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c  (C,V,N,D)], [sql
35920 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35930 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  16(C,V,N,D)],.**
35940 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
35950 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
35960 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72  be(C,V,N,D)], or
35970 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
35980 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35990 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16le(C,V,N,D)] 
359a0 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 0a  is the constant.
359b0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
359c0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74  ITE_TRANSIENT] t
359d0 68 65 6e 20 74 68 65 20 69 6e 74 65 72 66 61 63  hen the interfac
359e0 65 73 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  es makes a copy 
359f0 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
35a00 20 20 20 63 6f 6e 74 65 6e 74 20 6f 66 20 56 20     content of V 
35a10 61 6e 64 20 72 65 74 61 69 6e 73 20 74 68 65 20  and retains the 
35a20 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  copy..**.** {H16
35a30 34 36 33 7d 20 49 66 20 74 68 65 20 44 20 64 65  463} If the D de
35a40 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74  structor paramet
35a50 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  er to [sqlite3_r
35a60 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
35a70 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
35a80 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
35a90 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
35aa0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  , [sqlite3_resul
35ab0 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
35ac0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
35ad0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
35ae0 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
35af0 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
35b00 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
35b10 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
35b20 4e 2c 44 29 5d 20 69 73 20 73 6f 6d 65 20 76 61  N,D)] is some va
35b30 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a  lue other than.*
35b40 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63  *          the c
35b50 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45  onstants [SQLITE
35b60 5f 53 54 41 54 49 43 5d 20 61 6e 64 20 5b 53 51  _STATIC] and [SQ
35b70 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20  LITE_TRANSIENT] 
35b80 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
35b90 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
35ba0 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
35bb0 6f 72 20 44 20 77 69 74 68 20 56 20 61 73 20 69  or D with V as i
35bc0 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  ts only argument
35bd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65  .**          whe
35be0 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
35bf0 64 20 77 69 74 68 20 74 68 65 20 56 20 76 61 6c  d with the V val
35c00 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ue..*/.void sqli
35c10 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
35c20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35c30 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
35c40 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
35c50 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
35c60 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
35c70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35c80 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20  , double);.void 
35c90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35ca0 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e  rror(sqlite3_con
35cb0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
35cc0 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  r*, int);.void s
35cd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35ce0 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ror16(sqlite3_co
35cf0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
35d00 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
35d10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35d20 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69  rror_toobig(sqli
35d30 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
35d40 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35d50 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73  lt_error_nomem(s
35d60 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
35d70 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
35d80 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
35d90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35da0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
35db0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
35dc0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35dd0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
35de0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
35df0 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
35e00 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
35e10 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  64);.void sqlite
35e20 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71  3_result_null(sq
35e30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
35e40 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
35e50 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65  sult_text(sqlite
35e60 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
35e70 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f  t char*, int, vo
35e80 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
35e90 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35ea0 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  lt_text16(sqlite
35eb0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
35ec0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
35ed0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
35ee0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35ef0 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  lt_text16le(sqli
35f00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
35f10 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
35f20 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
35f30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35f40 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c  ult_text16be(sql
35f50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
35f60 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
35f70 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
35f80 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
35f90 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74  sult_value(sqlit
35fa0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
35fb0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f  ite3_value*);.vo
35fc0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35fd0 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
35fe0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
35ff0 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
36000 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
36010 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
36020 6e 63 65 73 20 7b 48 31 36 36 30 30 7d 20 3c 53  nces {H16600} <S
36030 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20300>.**.** The
36040 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
36050 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77   used to add new
36060 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
36070 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  nces to the.** [
36080 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36090 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61  ion] specified a
360a0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
360b0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
360c0 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20  name of the new 
360d0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
360e0 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20  ce is specified 
360f0 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  as a UTF-8 strin
36100 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
36110 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
36120 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
36130 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36140 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
36150 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72  TF-16 string for
36160 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
36170 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49  collation16(). I
36180 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74  n all cases.** t
36190 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65  he name is passe
361a0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
361b0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
361c0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  t..**.** The thi
361d0 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20  rd argument may 
361e0 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  be one of the co
361f0 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f  nstants [SQLITE_
36200 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  UTF8],.** [SQLIT
36210 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53  E_UTF16LE] or [S
36220 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20  QLITE_UTF16BE], 
36230 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
36240 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65  the user-supplie
36250 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70  d.** routine exp
36260 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65  ects to be passe
36270 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  d pointers to st
36280 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73  rings encoded us
36290 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54  ing UTF-8,.** UT
362a0 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69  F-16 little-endi
362b0 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
362c0 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g-endian, respec
362d0 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74  tively. The.** t
362e0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69  hird argument mi
362f0 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c  ght also be [SQL
36300 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
36310 44 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  D] to indicate t
36320 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69  hat.** the routi
36330 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74  ne expects point
36340 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f  ers to 16-bit wo
36350 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e  rd aligned strin
36360 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20  gs.** of UTF-16 
36370 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
36380 74 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te order of the 
36390 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a  host computer..*
363a0 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  *.** A pointer t
363b0 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c  o the user suppl
363c0 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  ied routine must
363d0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
363e0 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d  e fifth.** argum
363f0 65 6e 74 2e 20 20 49 66 20 69 74 20 69 73 20 4e  ent.  If it is N
36400 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65  ULL, this is the
36410 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e   same as deletin
36420 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  g the collation.
36430 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20  ** sequence (so 
36440 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e  that SQLite cann
36450 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f  ot call it anymo
36460 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d  re)..** Each tim
36470 65 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  e the applicatio
36480 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74  n supplied funct
36490 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ion is invoked, 
364a0 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20  it is passed.** 
364b0 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72  as its first par
364c0 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66  ameter a copy of
364d0 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65   the void* passe
364e0 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
364f0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
36500 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36510 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  llation() or sql
36520 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36530 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a  ation16()..**.**
36540 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61   The remaining a
36550 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
36560 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70  application-supp
36570 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65  lied routine are
36580 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a   two strings,.**
36590 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74 65   each represente
365a0 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20  d by a (length, 
365b0 64 61 74 61 29 20 70 61 69 72 20 61 6e 64 20 65  data) pair and e
365c0 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e  ncoded in the en
365d0 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77  coding.** that w
365e0 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  as passed as the
365f0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
36600 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  when the collati
36610 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a  on sequence was.
36620 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20 7b  ** registered. {
36630 45 4e 44 7d 20 20 54 68 65 20 61 70 70 6c 69 63  END}  The applic
36640 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f  ation defined co
36650 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20  llation routine 
36660 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
36670 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20   negative, zero 
36680 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 20 74  or positive if t
36690 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20  he first string 
366a0 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a  is less than,.**
366b0 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
366c0 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
366d0 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e  econd string. i.
366e0 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54  e. (STRING1 - ST
366f0 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  RING2)..**.** Th
36700 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
36710 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
36720 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
36730 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36740 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  ion().** except 
36750 74 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e  that it takes an
36760 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20   extra argument 
36770 77 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72  which is a destr
36780 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65  uctor for.** the
36790 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65   collation.  The
367a0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
367b0 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63  alled when the c
367c0 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  ollation is.** d
367d0 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20  estroyed and is 
367e0 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66  passed a copy of
367f0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
36800 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e  meter void* poin
36810 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ter.** of the sq
36820 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
36830 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20  lation_v2()..** 
36840 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64  Collations are d
36850 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68  estroyed when th
36860 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65  ey are overridde
36870 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73  n by later calls
36880 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61   to the.** colla
36890 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75  tion creation fu
368a0 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20  nctions or when 
368b0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
368c0 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f  nnection] is clo
368d0 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  sed.** using [sq
368e0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
368f0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
36900 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 33 7d  :.**.** {H16603}
36910 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
36920 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  ll to the.**    
36930 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
36940 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
36950 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
36960 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20   interface.**   
36970 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 73         registers
36980 20 66 75 6e 63 74 69 6f 6e 20 46 20 61 73 20 74   function F as t
36990 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75  he comparison fu
369a0 6e 63 74 69 6f 6e 20 75 73 65 64 20 74 6f 0a 2a  nction used to.*
369b0 2a 20 20 20 20 20 20 20 20 20 20 69 6d 70 6c 65  *          imple
369c0 6d 65 6e 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 58  ment collation X
369d0 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
369e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20  e connection] B 
369f0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
36a00 64 61 74 61 62 61 73 65 73 20 68 61 76 69 6e 67  databases having
36a10 20 65 6e 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a   encoding E..**.
36a20 2a 2a 20 7b 48 31 36 36 30 34 7d 20 53 51 4c 69  ** {H16604} SQLi
36a30 74 65 20 75 6e 64 65 72 73 74 61 6e 64 73 20 74  te understands t
36a40 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20 74  he X parameter t
36a50 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
36a60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36a70 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
36a80 2c 50 2c 46 2c 44 29 5d 20 61 73 20 61 20 7a 65  ,P,F,D)] as a ze
36a90 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
36aa0 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20            UTF-8 
36ab0 73 74 72 69 6e 67 20 69 6e 20 77 68 69 63 68 20  string in which 
36ac0 63 61 73 65 20 69 73 20 69 67 6e 6f 72 65 64 20  case is ignored 
36ad0 66 6f 72 20 41 53 43 49 49 20 63 68 61 72 61 63  for ASCII charac
36ae0 74 65 72 73 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ters and.**     
36af0 20 20 20 20 20 69 73 20 73 69 67 6e 69 66 69 63       is signific
36b00 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41 53 43 49  ant for non-ASCI
36b10 49 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  I characters..**
36b20 0a 2a 2a 20 7b 48 31 36 36 30 36 7d 20 53 75 63  .** {H16606} Suc
36b30 63 65 73 73 69 76 65 20 63 61 6c 6c 73 20 74 6f  cessive calls to
36b40 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36b50 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
36b60 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20  X,E,P,F,D)].**  
36b70 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68 65          with the
36b80 20 73 61 6d 65 20 76 61 6c 75 65 73 20 66 6f 72   same values for
36b90 20 42 2c 20 58 2c 20 61 6e 64 20 45 2c 20 6f 76   B, X, and E, ov
36ba0 65 72 72 69 64 65 20 70 72 69 6f 72 20 76 61 6c  erride prior val
36bb0 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ues.**          
36bc0 6f 66 20 50 2c 20 46 2c 20 61 6e 64 20 44 2e 0a  of P, F, and D..
36bd0 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 39 7d 20 49  **.** {H16609} I
36be0 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
36bf0 20 44 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63   D in [sqlite3_c
36c00 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
36c10 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
36c20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
36c30 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74  not NULL then it
36c40 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
36c50 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 20  argument P when 
36c60 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
36c70 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36c80 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 62 79  on is dropped by
36c90 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b   SQLite..**.** {
36ca0 48 31 36 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74  H16612} A collat
36cb0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
36cc0 64 72 6f 70 70 65 64 20 77 68 65 6e 20 69 74 20  dropped when it 
36cd0 69 73 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a  is overloaded..*
36ce0 2a 0a 2a 2a 20 7b 48 31 36 36 31 35 7d 20 41 20  *.** {H16615} A 
36cf0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36d00 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68  on is dropped wh
36d10 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
36d20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20  connection.**   
36d30 20 20 20 20 20 20 20 69 73 20 63 6c 6f 73 65 64         is closed
36d40 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
36d50 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  close()]..**.** 
36d60 7b 48 31 36 36 31 38 7d 20 54 68 65 20 70 6f 69  {H16618} The poi
36d70 6e 74 65 72 20 50 20 69 6e 20 5b 73 71 6c 69 74  nter P in [sqlit
36d80 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36d90 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
36da0 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,D)].**         
36db0 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
36dc0 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
36dd0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
36de0 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20   comparison.**  
36df0 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e          function
36e00 20 46 20 66 6f 72 20 61 6c 6c 20 73 75 62 73 65   F for all subse
36e10 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
36e20 73 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 48  s of F..**.** {H
36e30 31 36 36 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f  16621} A call to
36e40 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36e50 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45  _collation(B,X,E
36e60 2c 50 2c 46 29 5d 20 69 73 20 65 78 61 63 74 6c  ,P,F)] is exactl
36e70 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  y.**          th
36e80 65 20 73 61 6d 65 20 61 73 20 61 20 63 61 6c 6c  e same as a call
36e90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
36ea0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
36eb0 28 29 5d 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  ()] with.**     
36ec0 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 70 61       the same pa
36ed0 72 61 6d 65 74 65 72 73 20 61 6e 64 20 61 20 4e  rameters and a N
36ee0 55 4c 4c 20 64 65 73 74 72 75 63 74 6f 72 2e 0a  ULL destructor..
36ef0 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 34 7d 20 46  **.** {H16624} F
36f00 6f 6c 6c 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69  ollowing a [sqli
36f10 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36f20 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
36f30 46 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  F,D)],.**       
36f40 20 20 20 53 51 4c 69 74 65 20 75 73 65 73 20 74     SQLite uses t
36f50 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75  he comparison fu
36f60 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c  nction F for all
36f70 20 74 65 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e   text comparison
36f80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70 65  .**          ope
36f90 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 5b  rations on the [
36fa0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36fb0 69 6f 6e 5d 20 42 20 6f 6e 20 74 65 78 74 20 76  ion] B on text v
36fc0 61 6c 75 65 73 20 74 68 61 74 0a 2a 2a 20 20 20  alues that.**   
36fd0 20 20 20 20 20 20 20 75 73 65 20 74 68 65 20 63         use the c
36fe0 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63  ollating sequenc
36ff0 65 20 6e 61 6d 65 64 20 58 2e 0a 2a 2a 0a 2a 2a  e named X..**.**
37000 20 7b 48 31 36 36 32 37 7d 20 54 68 65 20 5b 73   {H16627} The [s
37010 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
37020 6c 6c 61 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c  llation16(B,X,E,
37030 50 2c 46 29 5d 20 77 6f 72 6b 73 20 74 68 65 20  P,F)] works the 
37040 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
37050 20 61 73 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   as [sqlite3_cre
37060 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c  ate_collation(B,
37070 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63 65 70 74  X,E,P,F)] except
37080 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20   that the.**    
37090 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20        collation 
370a0 6e 61 6d 65 20 58 20 69 73 20 75 6e 64 65 72 73  name X is unders
370b0 74 6f 6f 64 20 61 73 20 55 54 46 2d 31 36 20 69  tood as UTF-16 i
370c0 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
370d0 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
370e0 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38  instead of UTF-8
370f0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 33 30 7d  ..**.** {H16630}
37100 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63   When multiple c
37110 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69  omparison functi
37120 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ons are availabl
37130 65 20 66 6f 72 20 74 68 65 20 73 61 6d 65 0a 2a  e for the same.*
37140 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
37150 74 69 6e 67 20 73 65 71 75 65 6e 63 65 2c 20 53  ting sequence, S
37160 51 4c 69 74 65 20 63 68 6f 6f 73 65 73 20 74 68  QLite chooses th
37170 65 20 6f 6e 65 20 77 68 6f 73 65 20 74 65 78 74  e one whose text
37180 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 20 20 20   encoding.**    
37190 20 20 20 20 20 20 72 65 71 75 69 72 65 73 20 74        requires t
371a0 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
371b0 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72  of conversion fr
371c0 6f 6d 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  om the default.*
371d0 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20  *          text 
371e0 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20  encoding of the 
371f0 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74  database..*/.int
37200 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
37210 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c  collation(.  sql
37220 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
37230 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
37240 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
37250 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
37260 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
37270 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
37280 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
37290 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
372a0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
372b0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  v2(.  sqlite3*, 
372c0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
372d0 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
372e0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
372f0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
37300 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
37310 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
37320 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
37330 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
37340 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
37350 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
37360 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
37370 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  , .  const void 
37380 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54  *zName,.  int eT
37390 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a  extRep, .  void*
373a0 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
373b0 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
373c0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
373d0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
373e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
373f0 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43  llation Needed C
37400 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36 37 30 30  allbacks {H16700
37410 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20300>.**.**
37420 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67   To avoid having
37430 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c   to register all
37440 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
37450 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61  nces before a da
37460 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65  tabase.** can be
37470 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20   used, a single 
37480 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
37490 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
374a0 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  red with the.** 
374b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
374c0 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c  tion] to be call
374d0 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75  ed whenever an u
374e0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
374f0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69  on.** sequence i
37500 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  s required..**.*
37510 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f  * If the functio
37520 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  n is registered 
37530 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
37540 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37550 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65  ed() API,.** the
37560 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74  n it is passed t
37570 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65  he names of unde
37580 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
37590 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72  sequences as str
375a0 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20  ings.** encoded 
375b0 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31 36 37 30  in UTF-8. {H1670
375c0 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  3} If sqlite3_co
375d0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
375e0 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74  () is used,.** t
375f0 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73  he names are pas
37600 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  sed as UTF-16 in
37610 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20   machine native 
37620 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41  byte order..** A
37630 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
37640 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65  function replace
37650 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63  s any existing c
37660 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57  allback..**.** W
37670 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
37680 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65   is invoked, the
37690 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
376a0 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79  passed is a copy
376b0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  .** of the secon
376c0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
376d0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
376e0 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73  needed() or.** s
376f0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
37700 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68  _needed16().  Th
37710 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
37720 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  t is the databas
37730 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
37740 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
37750 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
37760 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53  SQLITE_UTF8], [S
37770 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a  QLITE_UTF16BE],.
37780 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ** or [SQLITE_UT
37790 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69  F16LE], indicati
377a0 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69  ng the most desi
377b0 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68  rable form of th
377c0 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  e collation.** s
377d0 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e  equence function
377e0 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20   required.  The 
377f0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
37800 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
37810 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20  the.** required 
37820 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
37830 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  ce..**.** The ca
37840 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
37850 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20  should register 
37860 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c  the desired coll
37870 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
37880 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37890 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  ollation()], [sq
378a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
378b0 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  lation16()], or.
378c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
378d0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
378e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
378f0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ANTS:.**.** {H16
37900 37 30 32 7d 20 41 20 73 75 63 63 65 73 73 66 75  702} A successfu
37910 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
37920 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
37930 64 65 64 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20  ded(D,P,F)].**  
37940 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
37950 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
37960 65 64 65 64 31 36 28 44 2c 50 2c 46 29 5d 20 63  eded16(D,P,F)] c
37970 61 75 73 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  auses.**        
37980 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20    the [database 
37990 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f  connection] D to
379a0 20 69 6e 76 6f 6b 65 20 63 61 6c 6c 62 61 63 6b   invoke callback
379b0 20 46 20 77 69 74 68 20 66 69 72 73 74 0a 2a 2a   F with first.**
379c0 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65            parame
379d0 74 65 72 20 50 20 77 68 65 6e 65 76 65 72 20 69  ter P whenever i
379e0 74 20 6e 65 65 64 73 20 61 20 63 6f 6d 70 61 72  t needs a compar
379f0 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 66 6f  ison function fo
37a00 72 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r a.**          
37a10 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e  collating sequen
37a20 63 65 20 74 68 61 74 20 69 74 20 64 6f 65 73 20  ce that it does 
37a30 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a  not know about..
37a40 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 34 7d 20 45  **.** {H16704} E
37a50 61 63 68 20 73 75 63 63 65 73 73 66 75 6c 20 63  ach successful c
37a60 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
37a70 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
37a80 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ()] or.**       
37a90 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c     [sqlite3_coll
37aa0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
37ab0 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 20  ] overrides the 
37ac0 63 61 6c 6c 62 61 63 6b 20 72 65 67 69 73 74 65  callback registe
37ad0 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
37ae0 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
37af0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37b00 5d 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73  ] by prior calls
37b10 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 20 20   to either.**   
37b20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
37b30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 36 7d  ..**.** {H16706}
37b40 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   The name of the
37b50 20 72 65 71 75 65 73 74 65 64 20 63 6f 6c 6c 61   requested colla
37b60 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ting function pa
37b70 73 73 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 20  ssed in the.**  
37b80 20 20 20 20 20 20 20 20 34 74 68 20 70 61 72 61          4th para
37b90 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
37ba0 6c 62 61 63 6b 20 69 73 20 69 6e 20 55 54 46 2d  lback is in UTF-
37bb0 38 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63  8 if the callbac
37bc0 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 61  k.**          wa
37bd0 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
37be0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ng [sqlite3_coll
37bf0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
37c00 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
37c10 69 73 20 69 6e 20 55 54 46 2d 31 36 20 6e 61 74  is in UTF-16 nat
37c20 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
37c30 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77  f the callback w
37c40 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  as.**          r
37c50 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
37c60 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
37c70 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
37c80 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
37c90 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
37ca0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
37cb0 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  void*, .  void(*
37cc0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
37cd0 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
37ce0 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e  nst char*).);.in
37cf0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
37d00 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20  ion_needed16(.  
37d10 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
37d20 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  d*,.  void(*)(vo
37d30 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
37d40 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
37d50 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
37d60 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
37d70 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
37d80 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
37d90 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
37da0 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
37db0 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
37dc0 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
37dd0 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
37de0 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
37df0 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
37e00 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
37e10 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
37e20 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
37e30 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  e3_key(.  sqlite
37e40 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
37e50 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
37e60 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
37e70 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
37e80 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
37e90 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
37ea0 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
37eb0 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e  hange the key on
37ec0 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
37ed0 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65  e.  If the curre
37ee0 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  nt database is n
37ef0 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c  ot.** encrypted,
37f00 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
37f10 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20  ll encrypt it.  
37f20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e  If pNew==0 or nN
37f30 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61  ew==0, the.** da
37f40 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70  tabase is decryp
37f50 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ted..**.** The c
37f60 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
37f70 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
37f80 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
37f90 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
37fa0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
37fb0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
37fc0 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
37fd0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
37fe0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
37ff0 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
38000 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
38010 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
38020 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
38030 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
38040 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e  CAPI3REF: Suspen
38050 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20  d Execution For 
38060 41 20 53 68 6f 72 74 20 54 69 6d 65 20 7b 48 31  A Short Time {H1
38070 30 35 33 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a  0530} <S40410>.*
38080 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
38090 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
380a0 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72  n causes the cur
380b0 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73  rent thread to s
380c0 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
380d0 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74  .** for at least
380e0 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c   a number of mil
380f0 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66  liseconds specif
38100 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d  ied in its param
38110 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  eter..**.** If t
38120 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
38130 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70  tem does not sup
38140 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65  port sleep reque
38150 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c  sts with.** mill
38160 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73  isecond time res
38170 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  olution, then th
38180 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72  e time will be r
38190 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20  ounded up to.** 
381a0 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f  the nearest seco
381b0 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  nd. The number o
381c0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  f milliseconds o
381d0 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
381e0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
381f0 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
38200 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
38210 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ned..**.** SQLit
38220 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69  e implements thi
38230 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63  s interface by c
38240 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65  alling the xSlee
38250 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  p().** method of
38260 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
38270 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
38280 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  t..**.** INVARIA
38290 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35  NTS:.**.** {H105
382a0 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  33} The [sqlite3
382b0 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72  _sleep(M)] inter
382c0 66 61 63 65 20 69 6e 76 6f 6b 65 73 20 74 68 65  face invokes the
382d0 20 78 53 6c 65 65 70 0a 2a 2a 20 20 20 20 20 20   xSleep.**      
382e0 20 20 20 20 6d 65 74 68 6f 64 20 6f 66 20 74 68      method of th
382f0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
38300 65 33 5f 76 66 73 7c 56 46 53 5d 20 69 6e 20 6f  e3_vfs|VFS] in o
38310 72 64 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  rder to.**      
38320 20 20 20 20 73 75 73 70 65 6e 64 20 65 78 65 63      suspend exec
38330 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72  ution of the cur
38340 72 65 6e 74 20 74 68 72 65 61 64 20 66 6f 72 20  rent thread for 
38350 61 74 20 6c 65 61 73 74 0a 2a 2a 20 20 20 20 20  at least.**     
38360 20 20 20 20 20 4d 20 6d 69 6c 6c 69 73 65 63 6f       M milliseco
38370 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35  nds..**.** {H105
38380 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  36} The [sqlite3
38390 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72  _sleep(M)] inter
383a0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
383b0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20   number of.**   
383c0 20 20 20 20 20 20 20 6d 69 6c 6c 69 73 65 63 6f         milliseco
383d0 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74  nds of sleep act
383e0 75 61 6c 6c 79 20 72 65 71 75 65 73 74 65 64 20  ually requested 
383f0 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  of the operating
38400 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 79 73  .**          sys
38410 74 65 6d 2c 20 77 68 69 63 68 20 6d 69 67 68 74  tem, which might
38420 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
38430 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4d 2e  the parameter M.
38440 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
38450 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
38460 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
38470 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
38480 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
38490 79 20 46 69 6c 65 73 20 7b 48 31 30 33 31 30 7d  y Files {H10310}
384a0 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20000>.**.** 
384b0 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
384c0 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
384d0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
384e0 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
384f0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
38500 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
38510 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
38520 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
38530 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
38540 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
38550 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64  placed in that d
38560 69 72 65 63 74 6f 72 79 2e 20 20 49 66 20 74 68  irectory.  If th
38570 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
38580 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
38590 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65  , then SQLite pe
385a0 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20  rforms a search 
385b0 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61  for an appropria
385c0 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
385d0 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a  file directory..
385e0 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  **.** It is not 
385f0 73 61 66 65 20 74 6f 20 6d 6f 64 69 66 79 20 74  safe to modify t
38600 68 69 73 20 76 61 72 69 61 62 6c 65 20 6f 6e 63  his variable onc
38610 65 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  e a [database co
38620 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 68 61 73  nnection].** has
38630 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 20 49   been opened.  I
38640 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68  t is intended th
38650 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
38660 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20   be set once.** 
38670 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65  as part of proce
38680 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
38690 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79  n and before any
386a0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
386b0 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61  e.** routines ha
386c0 76 65 20 62 65 65 6e 20 63 61 6c 6c 20 61 6e 64  ve been call and
386d0 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
386e0 64 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2f  d thereafter..*/
386f0 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
38700 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d  har *sqlite3_tem
38710 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  p_directory;../*
38720 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
38730 73 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d  st For Auto-Comm
38740 69 74 20 4d 6f 64 65 20 7b 48 31 32 39 33 30 7d  it Mode {H12930}
38750 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 4b 45 59   <S60200>.** KEY
38760 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d  WORDS: {autocomm
38770 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54  it mode}.**.** T
38780 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
38790 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65  utocommit() inte
387a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f  rface returns no
387b0 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72  n-zero or.** zer
387c0 6f 20 69 66 20 74 68 65 20 67 69 76 65 6e 20 64  o if the given d
387d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
387e0 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20  on is or is not 
387f0 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  in autocommit mo
38800 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  de,.** respectiv
38810 65 6c 79 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74  ely.  Autocommit
38820 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64   mode is on by d
38830 65 66 61 75 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63  efault..** Autoc
38840 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69  ommit mode is di
38850 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47  sabled by a [BEG
38860 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  IN] statement..*
38870 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64  * Autocommit mod
38880 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20  e is re-enabled 
38890 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72  by a [COMMIT] or
388a0 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a   [ROLLBACK]..**.
388b0 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69  ** If certain ki
388c0 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63  nds of errors oc
388d0 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65  cur on a stateme
388e0 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74  nt within a mult
388f0 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  i-statement.** t
38900 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f  ransaction (erro
38910 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51  rs including [SQ
38920 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_FULL], [SQL
38930