/ Hex Artifact Content
Login

Artifact 6cd2489e40fe97ba58c60044a4ced377e08b6d09:


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 32 31 20 32 30 30 38 2f 31  n,v 1.421 2008/1
05f0: 32 2f 33 30 20 30 36 3a 32 34 3a 35 38 20 64 61  2/30 06:24:58 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 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5640: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45  LITE_IOERR_CLOSE
5650: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5660: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36  LITE_IOERR | (16
5670: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5680: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43  LITE_IOERR_DIR_C
5690: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51  LOSE         (SQ
56a0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37  LITE_IOERR | (17
56b0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
56c0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
56d0: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
56e0: 74 69 6f 6e 73 20 7b 48 31 30 32 33 30 7d 20 3c  tions {H10230} <
56f0: 48 31 31 31 32 30 3e 20 3c 48 31 32 37 30 30 3e  H11120> <H12700>
5700: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74  .**.** These bit
5710: 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65   values are inte
5720: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
5730: 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d  the.** 3rd param
5740: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
5750: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
5760: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a  interface and.**
5770: 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61   in the 4th para
5780: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70  meter to the xOp
5790: 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  en method of the
57a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
57b0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
57c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
57d0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
57e0: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
57f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5800: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5810: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
5820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5830: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
5840: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
5850: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5860: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
5870: 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65    0x00000008.#de
5880: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5890: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
58a0: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
58b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
58c0: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
58d0: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
58e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
58f0: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
5900: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
5910: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5920: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
5930: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
5940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5950: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
5960: 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65    0x00000800.#de
5970: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5980: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
5990: 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 65    0x00001000.#de
59a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
59b0: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
59c0: 20 20 30 78 30 30 30 30 32 30 30 30 0a 23 64 65    0x00002000.#de
59d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
59e0: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
59f0: 20 20 30 78 30 30 30 30 34 30 30 30 0a 23 64 65    0x00004000.#de
5a00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5a10: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
5a20: 20 20 30 78 30 30 30 30 38 30 30 30 0a 23 64 65    0x00008000.#de
5a30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5a40: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
5a50: 20 20 30 78 30 30 30 31 30 30 30 30 0a 0a 2f 2a    0x00010000../*
5a60: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
5a70: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
5a80: 74 69 63 73 20 7b 48 31 30 32 34 30 7d 20 3c 48  tics {H10240} <H
5a90: 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  11120>.**.** The
5aa0: 20 78 44 65 76 69 63 65 43 61 70 61 62 69 6c 69   xDeviceCapabili
5ab0: 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ties method of t
5ac0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
5ad0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
5ae0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  t returns an int
5af0: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20  eger which is a 
5b00: 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68  vector of the th
5b10: 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65  ese.** bit value
5b20: 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f  s expressing I/O
5b30: 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73   characteristics
5b40: 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f   of the mass sto
5b50: 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74  rage.** device t
5b60: 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69  hat holds the fi
5b70: 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  le that the [sql
5b80: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
5b90: 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a  .** refers to..*
5ba0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
5bb0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
5bc0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
5bd0: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
5be0: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
5bf0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
5c00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
5c10: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
5c20: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
5c30: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
5c40: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
5c50: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
5c60: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
5c70: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
5c80: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
5c90: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
5ca0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
5cb0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
5cc0: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
5cd0: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
5ce0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
5cf0: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
5d00: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
5d10: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
5d20: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
5d30: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
5d40: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
5d50: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
5d60: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5d70: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
5d80: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
5d90: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
5da0: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
5db0: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
5dc0: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
5dd0: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23  o xWrite()..*/.#
5de0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5df0: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
5e00: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
5e10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5e20: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
5e30: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23      0x00000002.#
5e40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5e50: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20  CAP_ATOMIC1K    
5e60: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
5e70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5e80: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20  CAP_ATOMIC2K    
5e90: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
5ea0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5eb0: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
5ec0: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
5ed0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5ee0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
5ef0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23      0x00000020.#
5f00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5f10: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20  CAP_ATOMIC16K   
5f20: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
5f30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5f40: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
5f50: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
5f60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5f70: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
5f80: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
5f90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5fa0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
5fb0: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23      0x00000200.#
5fc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5fd0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20  CAP_SEQUENTIAL  
5fe0: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 0a      0x00000400..
5ff0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6000: 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76  File Locking Lev
6010: 65 6c 73 20 7b 48 31 30 32 35 30 7d 20 3c 48 31  els {H10250} <H1
6020: 31 31 32 30 3e 20 3c 48 31 31 33 31 30 3e 0a 2a  1120> <H11310>.*
6030: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
6040: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
6050: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6060: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
6070: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
6080: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
6090: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
60a0: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
60b0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
60c0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
60d0: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
60e0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
60f0: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
6100: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
6110: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
6120: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6130: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
6140: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
6150: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
6160: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
6170: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6180: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
6190: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
61a0: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
61b0: 20 46 6c 61 67 73 20 7b 48 31 30 32 36 30 7d 20   Flags {H10260} 
61c0: 3c 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 57  <H11120>.**.** W
61d0: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
61e0: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
61f0: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
6200: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6210: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
6220: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
6230: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
6240: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
6250: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
6260: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
6270: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
6280: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
6290: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
62a0: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
62b0: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
62c0: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
62d0: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
62e0: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
62f0: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
6300: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 54  ot be flushed. T
6310: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
6320: 4f 52 4d 41 4c 20 66 6c 61 67 20 6d 65 61 6e 73  ORMAL flag means
6330: 0a 2a 2a 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61  .** to use norma
6340: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74  l fsync() semant
6350: 69 63 73 2e 20 54 68 65 20 53 51 4c 49 54 45 5f  ics. The SQLITE_
6360: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 20 6d  SYNC_FULL flag m
6370: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
6380: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
6390: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
63a0: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a 23 64  f fsync()..*/.#d
63b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
63c0: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20  C_NORMAL        
63d0: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0x00002.#define 
63e0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
63f0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6400: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
6410: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20  _SYNC_DATAONLY  
6420: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a      0x00010../*.
6430: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
6440: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
6450: 69 6c 65 20 48 61 6e 64 6c 65 20 7b 48 31 31 31  ile Handle {H111
6460: 31 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a 2a 0a  10} <S20110>.**.
6470: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
6480: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
6490: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
64a0: 69 6c 65 20 69 6e 20 74 68 65 20 4f 53 0a 2a 2a  ile in the OS.**
64b0: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
64c0: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
64d0: 20 69 6e 74 65 72 66 61 63 65 20 69 6d 70 6c 65   interface imple
64e0: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
64f0: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
6500: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
6510: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
6520: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
6530: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
6540: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
6550: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
6560: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
6570: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6580: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
6590: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
65a0: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
65b0: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
65c0: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
65d0: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
65e0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
65f0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
6600: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
6610: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
6620: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
6630: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
6640: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
6650: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
6660: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
6670: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
6680: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
6690: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20   Methods Object 
66a0: 7b 48 31 31 31 32 30 7d 20 3c 53 32 30 31 31 30  {H11120} <S20110
66b0: 3e 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69  >.**.** Every fi
66c0: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65  le opened by the
66d0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
66e0: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75  Open method popu
66f0: 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c  lates an.** [sql
6700: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
6710: 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d  t (or, more comm
6720: 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73  only, a subclass
6730: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
6740: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
6750: 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
6760: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
6770: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a  of this object..
6780: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64  ** This object d
6790: 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f  efines the metho
67a0: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f  ds used to perfo
67b0: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61  rm various opera
67c0: 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74  tions.** against
67d0: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72   the open file r
67e0: 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68  epresented by th
67f0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
6800: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54   object..**.** T
6810: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
6820: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62  t to xSync may b
6830: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  e one of [SQLITE
6840: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72  _SYNC_NORMAL] or
6850: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  .** [SQLITE_SYNC
6860: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72  _FULL].  The fir
6870: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65  st choice is the
6880: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e   normal fsync().
6890: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
68a0: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f  hoice is a Mac O
68b0: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
68c0: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  nc.  The [SQLITE
68d0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a  _SYNC_DATAONLY].
68e0: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f  ** flag may be O
68f0: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61  Red in to indica
6900: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
6910: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
6920: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73  e.** and not its
6930: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20   inode needs to 
6940: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a  be synced..**.**
6950: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
6960: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
6970: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
6980: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
6990: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
69a0: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
69b0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
69c0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
69d0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
69e0: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
69f0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
6a00: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
6a10: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6a20: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
6a30: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
6a40: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
6a50: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
6a60: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
6a70: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b  k..** The xCheck
6a80: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d  ReservedLock() m
6a90: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65  ethod checks whe
6aa0: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73  ther any databas
6ab0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a  e connection,.**
6ac0: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20   either in this 
6ad0: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f  process or in so
6ae0: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  me other process
6af0: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52  , is holding a R
6b00: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
6b10: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
6b20: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
6b30: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
6b40: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
6b50: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
6b60: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73  d false otherwis
6b70: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69  e..**.** The xFi
6b80: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68  leControl() meth
6b90: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  od is a generic 
6ba0: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
6bb0: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20  llows custom.** 
6bc0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
6bd0: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20  ons to directly 
6be0: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20  control an open 
6bf0: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  file using the.*
6c00: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
6c10: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
6c20: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  face.  The secon
6c30: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20  d "op" argument 
6c40: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  is an.** integer
6c50: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68   opcode.  The th
6c60: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
6c70: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
6c80: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a  r intended to.**
6c90: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75   point to a stru
6ca0: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
6cb0: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
6cc0: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
6cd0: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
6ce0: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
6cf0: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
6d00: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
6d10: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
6d20: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
6d30: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
6d40: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
6d50: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
6d60: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
6d70: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
6d80: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
6d90: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
6da0: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
6db0: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
6dc0: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
6dd0: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
6de0: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
6df0: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65  erves all opcode
6e00: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  s less than 100 
6e10: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e  for its own use.
6e20: 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43  .** A [SQLITE_FC
6e30: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20  NTL_LOCKSTATE | 
6e40: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
6e50: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
6e60: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
6e70: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
6e80: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
6e90: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
6ea0: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
6eb0: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
6ec0: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
6ed0: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
6ee0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
6ef0: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
6f00: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
6f10: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
6f20: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
6f30: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
6f40: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
6f50: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
6f60: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
6f70: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
6f80: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
6f90: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
6fa0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
6fb0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
6fc0: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
6fd0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
6fe0: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
6ff0: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
7000: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
7010: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
7020: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
7030: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7040: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
7050: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7060: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <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 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
7090: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
70a0: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
70b0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
70c0: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
70d0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
70e0: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
70f0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7100: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
7110: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7120: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
7130: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7140: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
7150: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7160: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
7170: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7180: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
7190: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
71a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
71b0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
71c0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
71d0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
71e0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
71f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
7200: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
7210: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
7220: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
7230: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
7240: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
7250: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
7260: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
7270: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
7280: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
7290: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
72a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
72b0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
72c0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
72d0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
72e0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
72f0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
7300: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
7310: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
7320: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
7330: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
7340: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
7350: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
7360: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
7370: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
7380: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
7390: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
73a0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
73b0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
73c0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
73d0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
73e0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
73f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
7400: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
7410: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
7420: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
7430: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
7440: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
7450: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
7460: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
7470: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
7480: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
7490: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
74a0: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
74b0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
74c0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
74d0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
74e0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
74f0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
7500: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7510: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
7520: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
7530: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7540: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
7550: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
7560: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7570: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
7580: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7590: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
75a0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
75b0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
75c0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
75d0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
75e0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
75f0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
7600: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
7610: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
7620: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
7630: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
7640: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
7650: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
7660: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
7670: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
7680: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7690: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
76a0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
76b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
76c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
76d0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
76e0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
76f0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
7700: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
7710: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
7720: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
7730: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
7740: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
7750: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
7760: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
7770: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
7780: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
7790: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
77a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
77b0: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
77c0: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
77d0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
77e0: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
77f0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7800: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
7810: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 20 7b 48  ntrol Opcodes {H
7820: 31 31 33 31 30 7d 20 3c 53 33 30 38 30 30 3e 0a  11310} <S30800>.
7830: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
7840: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
7850: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
7860: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
7870: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
7880: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
7890: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
78a0: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
78b0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
78c0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  .** interface..*
78d0: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
78e0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
78f0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
7900: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
7910: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
7920: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
7930: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
7940: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
7950: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
7960: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
7970: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
7980: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
7990: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
79a0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
79b0: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
79c0: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
79d0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
79e0: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
79f0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
7a00: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
7a10: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
7a20: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
7a30: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
7a40: 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79  testing and only
7a50: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
7a60: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
7a70: 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65  TE_TEST.** is de
7a80: 66 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e  fined..*/.#defin
7a90: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
7aa0: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20  OCKSTATE        
7ab0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
7ac0: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
7ad0: 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  LE      2.#defin
7ae0: 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43  e SQLITE_SET_LOC
7af0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
7b00: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
7b10: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
7b20: 20 20 20 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a          4../*.**
7b30: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
7b40: 20 48 61 6e 64 6c 65 20 7b 48 31 37 31 31 30 7d   Handle {H17110}
7b50: 20 3c 53 32 30 31 33 30 3e 0a 2a 2a 0a 2a 2a 20   <S20130>.**.** 
7b60: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
7b70: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
7b80: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
7b90: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
7ba0: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
7bb0: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
7bc0: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
7bd0: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
7be0: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
7bf0: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
7c00: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
7c10: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
7c20: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
7c30: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
7c40: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
7c50: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7c60: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
7c70: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
7c80: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
7c90: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
7ca0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
7cb0: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
7cc0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7cd0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7ce0: 4f 62 6a 65 63 74 20 7b 48 31 31 31 34 30 7d 20  Object {H11140} 
7cf0: 3c 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41  <S20100>.**.** A
7d00: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
7d10: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
7d20: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
7d30: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
7d40: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
7d50: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
7d60: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
7d70: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
7d80: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
7d90: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
7da0: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
7db0: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
7dc0: 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76  em"..**.** The v
7dd0: 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72  alue of the iVer
7de0: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e  sion field is in
7df0: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61  itially 1 but ma
7e00: 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a  y be larger in.*
7e10: 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  * future version
7e20: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64  s of SQLite.  Ad
7e30: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
7e40: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
7e50: 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63  to this.** objec
7e60: 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73  t when the iVers
7e70: 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63  ion value is inc
7e80: 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68  reased.  Note th
7e90: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
7ea0: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
7eb0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
7ec0: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
7ed0: 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  nsaction between
7ee0: 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
7ef0: 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36  on 3.5.9 and 3.6
7f00: 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  .0 and yet the i
7f10: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
7f20: 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65  s not.** modifie
7f30: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
7f40: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
7f50: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
7f60: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74  ubclassed [sqlit
7f70: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75  e3_file].** stru
7f80: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
7f90: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
7fa0: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
7fb0: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
7fc0: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
7fd0: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65  is VFS..**.** Re
7fe0: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33  gistered sqlite3
7ff0: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65  _vfs objects are
8000: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65   kept on a linke
8010: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79  d list formed by
8020: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f  .** the pNext po
8030: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c  inter.  The [sql
8040: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
8050: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  r()].** and [sql
8060: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
8070: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ter()] interface
8080: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69  s manage this li
8090: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61  st.** in a threa
80a0: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65  d-safe way.  The
80b0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   [sqlite3_vfs_fi
80c0: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  nd()] interface.
80d0: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20  ** searches the 
80e0: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74  list.  Neither t
80f0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  he application c
8100: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a  ode nor the VFS.
8110: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
8120: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  n should use the
8130: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a   pNext pointer..
8140: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
8150: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
8160: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73  y field in the s
8170: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74  qlite3_vfs.** st
8180: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c  ructure that SQL
8190: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f  ite will ever mo
81a0: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69  dify.  SQLite wi
81b0: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a  ll only access.*
81c0: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  * or modify this
81d0: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c   field while hol
81e0: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61  ding a particula
81f0: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  r static mutex..
8200: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
8210: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
8220: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20  modify anything 
8230: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74  within the sqlit
8240: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74  e3_vfs.** object
8250: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74   once the object
8260: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74   has been regist
8270: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ered..**.** The 
8280: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64  zName field hold
8290: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
82a0: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54  e VFS module.  T
82b0: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20  he name must.** 
82c0: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73  be unique across
82d0: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73   all VFS modules
82e0: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
82f0: 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74 68  ill guarantee th
8300: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
8310: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
8320: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
8330: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
8340: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
8350: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
8360: 50 61 74 68 6e 61 6d 65 28 29 2e 20 20 53 51 4c  Pathname().  SQL
8370: 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72  ite further guar
8380: 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74  antees that.** t
8390: 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
83a0: 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68  e valid and unch
83b0: 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f  anged until xClo
83c0: 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  se() is.** calle
83d0: 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  d. Because of th
83e0: 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
83f0: 6e 73 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  nse,.** the [sql
8400: 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73  ite3_file] can s
8410: 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f  afely store a po
8420: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
8430: 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e  filename if it n
8440: 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72  eeds to remember
8450: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f   the filename fo
8460: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a  r some reason..*
8470: 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61  * If the zFilena
8480: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
8490: 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20  xOpen is a NULL 
84a0: 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70  pointer then xOp
84b0: 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 69 74  en.** must invit
84c0: 65 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72  e its own tempor
84d0: 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65  ary name for the
84e0: 20 66 69 6c 65 2e 20 20 57 68 65 6e 65 76 65 72   file.  Whenever
84f0: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61   the .** xFilena
8500: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
8510: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73  NULL it will als
8520: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  o be the case th
8530: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20  at the.** flags 
8540: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69  parameter will i
8550: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
8560: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8570: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  E]..**.** The fl
8580: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
8590: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73  xOpen() includes
85a0: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e   all bits set in
85b0: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72  .** the flags ar
85c0: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
85d0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20  e3_open_v2()].  
85e0: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f  Or if [sqlite3_o
85f0: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  pen()].** or [sq
8600: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
8610: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c  is used, then fl
8620: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20  ags includes at 
8630: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45  least.** [SQLITE
8640: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
8650: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
8660: 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20  CREATE]. .** If 
8670: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
8680: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
8690: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
86a0: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
86b0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
86c0: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
86d0: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
86e0: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65  tFlags may be se
86f0: 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  t..**.** SQLite 
8700: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
8710: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
8720: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
8730: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
8740: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
8750: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
8760: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
8770: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
8780: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
8790: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
87a0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
87b0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
87c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
87d0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
87e0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
87f0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
8800: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
8810: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
8820: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
8830: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
8840: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
8850: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
8860: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  AL].** </ul>.**.
8870: 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20  ** The file I/O 
8880: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63  implementation c
8890: 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63  an use the objec
88a0: 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a  t type flags to.
88b0: 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61  ** change the wa
88c0: 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20  y it deals with 
88d0: 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d  files.  For exam
88e0: 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
88f0: 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73  ion.** that does
8900: 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20   not care about 
8910: 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f  crash recovery o
8920: 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74  r rollback might
8930: 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65   make.** the ope
8940: 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66  n of a journal f
8950: 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72  ile a no-op.  Wr
8960: 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75  ites to this jou
8970: 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c  rnal would.** al
8980: 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e  so be no-ops, an
8990: 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  d any attempt to
89a0: 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61   read the journa
89b0: 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a  l would return.*
89c0: 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20  * SQLITE_IOERR. 
89d0: 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e   Or the implemen
89e0: 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63  tation might rec
89f0: 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61  ognize that a da
8a00: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77  tabase.** file w
8a10: 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67  ill be doing pag
8a20: 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72  e-aligned sector
8a30: 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65   reads and write
8a40: 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a  s in a random.**
8a50: 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75   order and set u
8a60: 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73  p its I/O subsys
8a70: 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e  tem accordingly.
8a80: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69  .**.** SQLite mi
8a90: 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ght also add one
8aa0: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
8ab0: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
8ac0: 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Open method:.**.
8ad0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
8ae0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
8af0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c  ETEONCLOSE].** <
8b00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
8b10: 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c  _EXCLUSIVE].** <
8b20: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  /ul>.**.** The [
8b30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
8b40: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20  TEONCLOSE] flag 
8b50: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
8b60: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65  hould be.** dele
8b70: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  ted when it is c
8b80: 6c 6f 73 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  losed.  The [SQL
8b90: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
8ba0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20  NCLOSE].** will 
8bb0: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
8bc0: 20 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75 72   databases, jour
8bd0: 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75 62  nals and for sub
8be0: 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20  journals..**.** 
8bf0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
8c00: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
8c10: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
8c20: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
8c30: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
8c40: 65 20 61 63 63 65 73 73 2e 20 20 54 68 69 73 20  e access.  This 
8c50: 66 6c 61 67 20 69 73 20 73 65 74 20 66 6f 72 20  flag is set for 
8c60: 61 6c 6c 20 66 69 6c 65 73 20 65 78 63 65 70 74  all files except
8c70: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 61 69 6e  .** for the main
8c80: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
8c90: 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74 20 73  **.** At least s
8ca0: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
8cb0: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
8cc0: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
8cd0: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
8ce0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
8cf0: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
8d00: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
8d10: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
8d20: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
8d30: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
8d40: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
8d50: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
8d60: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
8d70: 66 69 6c 6c 20 69 74 20 69 6e 2e 0a 2a 2a 0a 2a  fill it in..**.*
8d80: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
8d90: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28  ment to xAccess(
8da0: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45  ) may be [SQLITE
8db0: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a  _ACCESS_EXISTS].
8dc0: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74  ** to test for t
8dd0: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20  he existence of 
8de0: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  a file, or [SQLI
8df0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
8e00: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20  ITE] to.** test 
8e10: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
8e20: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  s readable and w
8e30: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c  ritable, or [SQL
8e40: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d  ITE_ACCESS_READ]
8e50: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74  .** to test whet
8e60: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74  her a file is at
8e70: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
8e80: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20     The file can 
8e90: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72  be a.** director
8ea0: 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  y..**.** SQLite 
8eb0: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
8ec0: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
8ed0: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
8ee0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
8ef0: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
8f00: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
8f10: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
8f20: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
8f30: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
8f40: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
8f50: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
8f60: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
8f70: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
8f80: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
8f90: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
8fa0: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
8fb0: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
8fc0: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
8fd0: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
8fe0: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
8ff0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
9000: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
9010: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
9020: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
9030: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
9040: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
9050: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
9060: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
9070: 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75 72  leep(), and xCur
9080: 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65 72  rentTime() inter
9090: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
90a0: 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74   strictly a part
90b0: 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74   of the filesyst
90c0: 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65  em, but they are
90d0: 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  .** included in 
90e0: 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72  the VFS structur
90f0: 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65  e for completene
9100: 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  ss..** The xRand
9110: 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f  omness() functio
9120: 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  n attempts to re
9130: 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65  turn nBytes byte
9140: 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61  s.** of good-qua
9150: 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20  lity randomness 
9160: 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20  into zOut.  The 
9170: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a  return value is.
9180: 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75  ** the actual nu
9190: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66  mber of bytes of
91a0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
91b0: 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c  ined..** The xSl
91c0: 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75  eep() method cau
91d0: 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ses the calling 
91e0: 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20  thread to sleep 
91f0: 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20  for at.** least 
9200: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
9210: 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e  croseconds given
9220: 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e 74 54  .  The xCurrentT
9230: 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ime().** method 
9240: 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e  returns a Julian
9250: 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20   Day Number for 
9260: 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65  the current date
9270: 20 61 6e 64 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2f   and time..**.*/
9280: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
9290: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69  sqlite3_vfs sqli
92a0: 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20  te3_vfs;.struct 
92b0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
92c0: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
92d0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
92e0: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
92f0: 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a  mber */.  int sz
9300: 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20  OsFile;         
9310: 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75     /* Size of su
9320: 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33  bclassed sqlite3
9330: 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d  _file */.  int m
9340: 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20  xPathname;      
9350: 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66      /* Maximum f
9360: 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e  ile pathname len
9370: 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  gth */.  sqlite3
9380: 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20  _vfs *pNext;    
9390: 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74    /* Next regist
93a0: 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f  ered VFS */.  co
93b0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b  nst char *zName;
93c0: 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
93d0: 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66  f this virtual f
93e0: 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20  ile system */.  
93f0: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
9400: 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e           /* Poin
9410: 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69  ter to applicati
9420: 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61  on-specific data
9430: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65   */.  int (*xOpe
9440: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
9450: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
9460: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  me, sqlite3_file
9470: 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  *,.             
9480: 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74    int flags, int
9490: 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20   *pOutFlags);.  
94a0: 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73  int (*xDelete)(s
94b0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
94c0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
94d0: 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20  int syncDir);.  
94e0: 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73  int (*xAccess)(s
94f0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
9500: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
9510: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
9520: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
9530: 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29  (*xFullPathname)
9540: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
9550: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
9560: 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72  , int nOut, char
9570: 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20   *zOut);.  void 
9580: 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69  *(*xDlOpen)(sqli
9590: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
95a0: 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29  char *zFilename)
95b0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72  ;.  void (*xDlEr
95c0: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
95d0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
95e0: 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20  ar *zErrMsg);.  
95f0: 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29  void (*(*xDlSym)
9600: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f  (sqlite3_vfs*,vo
9610: 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  id*, const char 
9620: 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29  *zSymbol))(void)
9630: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c  ;.  void (*xDlCl
9640: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ose)(sqlite3_vfs
9650: 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  *, void*);.  int
9660: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
9670: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
9680: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
9690: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Out);.  int (*xS
96a0: 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66  leep)(sqlite3_vf
96b0: 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63  s*, int microsec
96c0: 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  onds);.  int (*x
96d0: 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c  CurrentTime)(sql
96e0: 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c  ite3_vfs*, doubl
96f0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  e*);.  int (*xGe
9700: 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69  tLastError)(sqli
9710: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63  te3_vfs*, int, c
9720: 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77  har *);.  /* New
9730: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
9740: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
9750: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
9760: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
9770: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
9780: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
9790: 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b  s happens. */.};
97a0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
97b0: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
97c0: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
97d0: 6f 64 20 7b 48 31 31 31 39 30 7d 20 3c 48 31 31  od {H11190} <H11
97e0: 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  140>.**.** These
97f0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
9800: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
9810: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
9820: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
9830: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
9840: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
9850: 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44 7d  s] object. {END}
9860: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
9870: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
9880: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
9890: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
98a0: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
98b0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
98c0: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
98d0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
98e0: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
98f0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
9900: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
9910: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
9920: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
9930: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
9940: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
9950: 20 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f 74   the file is bot
9960: 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  h readable and w
9970: 72 69 74 61 62 6c 65 2e 0a 2a 2a 20 57 69 74 68  ritable..** With
9980: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
9990: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
99a0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
99b0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
99c0: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 0a  le is readable..
99d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
99e0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
99f0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
9a00: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
9a10: 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20 53  RITE 1.#define S
9a20: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
9a30: 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a 20  D      2../*.** 
9a40: 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61  CAPI3REF: Initia
9a50: 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20  lize The SQLite 
9a60: 4c 69 62 72 61 72 79 20 7b 48 31 30 31 33 30 7d  Library {H10130}
9a70: 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 31 30 30   <S20000><S30100
9a80: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
9a90: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9aa0: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
9ab0: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
9ac0: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
9ad0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
9ae0: 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64  n() routine.** d
9af0: 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72  eallocates any r
9b00: 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65  esources that we
9b10: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
9b20: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9b30: 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ze()..**.** A ca
9b40: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
9b50: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e  itialize() is an
9b60: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
9b70: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68  l 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 20 64 75 72  ) is invoked dur
9bb0: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
9bc0: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65   of.** the proce
9bd0: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20  ss, or if it is 
9be0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
9bf0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9c00: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
9c10: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  * following a ca
9c20: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
9c30: 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79 20  utdown().  Only 
9c40: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
9c50: 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  l.** of sqlite3_
9c60: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65  initialize() doe
9c70: 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61  s any initializa
9c80: 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72  tion.  All other
9c90: 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61   calls.** are ha
9ca0: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a 2a  rmless no-ops..*
9cb0: 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72  *.** Among other
9cc0: 20 74 68 69 6e 67 73 2c 20 73 71 6c 69 74 65 33   things, sqlite3
9cd0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 68  _initialize() sh
9ce0: 61 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  all invoke.** sq
9cf0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
9d00: 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 73 71 6c    Similarly, sql
9d10: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
9d20: 2a 2a 20 73 68 61 6c 6c 20 69 6e 76 6f 6b 65 20  ** shall invoke 
9d30: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
9d40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
9d50: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9d60: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
9d70: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
9d80: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 49 66 20 66  success..** If f
9d90: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20  or some reason, 
9da0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9db0: 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  ze() is unable t
9dc0: 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20  o initialize.** 
9dd0: 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72  the library (per
9de0: 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c  haps it is unabl
9df0: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20  e to allocate a 
9e00: 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20  needed resource 
9e10: 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74  such.** as a mut
9e20: 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61  ex) it returns a
9e30: 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
9e40: 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
9e50: 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  E_OK]..**.** The
9e60: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9e70: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
9e80: 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
9e90: 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
9ea0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
9eb0: 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
9ec0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
9ed0: 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
9ee0: 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
9ef0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9f00: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
9f10: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
9f20: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
9f30: 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
9f40: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
9f50: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
9f60: 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
9f70: 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
9f80: 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
9f90: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
9fa0: 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
9fb0: 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
9fc0: 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
9fd0: 20 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c   However, if SQL
9fe0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
9ff0: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
a000: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
a010: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
a020: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
a030: 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
a040: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
a050: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
a060: 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
a070: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
a080: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
a090: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
a0a0: 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
a0b0: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
a0c0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
a0d0: 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
a0e0: 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
a0f0: 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
a100: 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
a110: 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
a120: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a130: 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
a140: 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
a150: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
a160: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
a170: 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
a180: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
a190: 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
a1a0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
a1b0: 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
a1c0: 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
a1d0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
a1e0: 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
a1f0: 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
a200: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
a210: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
a220: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
a230: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
a240: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
a250: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
a260: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
a270: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
a280: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
a290: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
a2a0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
a2b0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
a2c0: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
a2d0: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
a2e0: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
a2f0: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
a300: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
a310: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
a320: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
a330: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
a340: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
a350: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
a360: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
a370: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
a380: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
a390: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
a3a0: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
a3b0: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
a3c0: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
a3d0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
a3e0: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
a3f0: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
a400: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
a410: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
a420: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
a430: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
a440: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
a450: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
a460: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
a470: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
a480: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a490: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
a4a0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
a4b0: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
a4c0: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
a4d0: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
a4e0: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
a4f0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
a500: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
a510: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
a520: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
a530: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
a540: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
a550: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
a560: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a570: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
a580: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
a590: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
a5a0: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
a5b0: 65 64 20 66 6f 72 20 75 6e 69 78 2c 20 77 69 6e  ed for unix, win
a5c0: 64 6f 77 73 2c 20 6f 72 20 6f 73 2f 32 2e 0a 2a  dows, or os/2..*
a5d0: 2a 20 57 68 65 6e 20 62 75 69 6c 74 20 66 6f 72  * When built for
a5e0: 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
a5f0: 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c   (using the [SQL
a600: 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20  ITE_OS_OTHER=1] 
a610: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
a620: 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c  option) the appl
a630: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
a640: 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69  ply a suitable i
a650: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
a660: 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  r.** sqlite3_os_
a670: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
a680: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e  e3_os_end().  An
a690: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
a6a0: 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65  plied.** impleme
a6b0: 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
a6c0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20  e3_os_init() or 
a6d0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
a6e0: 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20  .** must return 
a6f0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
a700: 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20  uccess and some 
a710: 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64  other [error cod
a720: 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75  e] upon.** failu
a730: 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  re..*/.int sqlit
a740: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
a750: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
a760: 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
a770: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
a780: 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20  init(void);.int 
a790: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
a7a0: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
a7b0: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
a7c0: 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
a7d0: 62 72 61 72 79 20 7b 48 31 34 31 30 30 7d 20 3c  brary {H14100} <
a7e0: 53 32 30 30 30 30 3e 3c 53 33 30 32 30 30 3e 0a  S20000><S30200>.
a7f0: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
a800: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
a810: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
a820: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
a830: 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
a840: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
a850: 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
a860: 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
a870: 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
a880: 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
a890: 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
a8a0: 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
a8b0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
a8c0: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
a8d0: 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
a8e0: 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
a8f0: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
a900: 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
a910: 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
a920: 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
a930: 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
a940: 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
a950: 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  l needs..**.** T
a960: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
a970: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
a980: 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
a990: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
a9a0: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65  n.** must insure
a9b0: 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
a9c0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
a9d0: 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
a9e0: 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
a9f0: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
aa00: 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
aa10: 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65  ng.  Furthermore
aa20: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
aa30: 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ().** may only b
aa40: 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20  e invoked prior 
aa50: 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69  to library initi
aa60: 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a  alization using.
aa70: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ** [sqlite3_init
aa80: 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  ialize()] or aft
aa90: 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b  er shutdown by [
aaa0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
aab0: 28 29 5d 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  ()]..** Note, ho
aac0: 77 65 76 65 72 2c 20 74 68 61 74 20 73 71 6c 69  wever, that sqli
aad0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
aae0: 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
aaf0: 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
ab00: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
ab10: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
ab20: 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
ab30: 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
ab40: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
ab50: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
ab60: 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
ab70: 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  teger.** [SQLITE
ab80: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
ab90: 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61  READ | configura
aba0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
abb0: 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
abc0: 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
abd0: 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
abe0: 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
abf0: 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
ac00: 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
ac10: 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c  ding on the [SQL
ac20: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
ac30: 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67  ETHREAD | config
ac40: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
ac50: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
ac60: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
ac70: 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
ac80: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
ac90: 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
aca0: 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
acb0: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 49 66 20  LITE_OK]..** If 
acc0: 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
acd0: 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
ace0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
acf0: 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
ad00: 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
ad10: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
ad20: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
ad30: 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
ad40: 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 30  TS:.**.** {H1410
ad50: 33 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  3} A successful 
ad60: 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
ad70: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
ad80: 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a   shall return.**
ad90: 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
ada0: 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  E_OK]..**.** {H1
adb0: 34 31 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74  4106} The [sqlit
adc0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
add0: 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 74  erface shall ret
ade0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  urn [SQLITE_MISU
adf0: 53 45 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  SE].**          
ae00: 69 66 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64  if it is invoked
ae10: 20 69 6e 20 62 65 74 77 65 65 6e 20 63 61 6c 6c   in between call
ae20: 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69 6e  s to [sqlite3_in
ae30: 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 0a  itialize()] and.
ae40: 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
ae50: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
ae60: 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32 30 7d  ..**.** {H14120}
ae70: 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
ae80: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
ae90: 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
aea0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
aeb0: 41 44 5d 29 0a 2a 2a 20 20 20 20 20 20 20 20 20  AD]).**         
aec0: 20 73 68 61 6c 6c 20 73 65 74 20 74 68 65 20 64   shall set the d
aed0: 65 66 61 75 6c 74 20 5b 74 68 72 65 61 64 69 6e  efault [threadin
aee0: 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
aef0: 65 2d 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e-thread..**.** 
af00: 7b 48 31 34 31 32 33 7d 20 41 20 73 75 63 63 65  {H14123} A succe
af10: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
af20: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
af30: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
af40: 4c 54 49 54 48 52 45 41 44 5d 29 0a 2a 2a 20 20  LTITHREAD]).**  
af50: 20 20 20 20 20 20 20 20 73 68 61 6c 6c 20 73 65          shall se
af60: 74 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 74  t the default [t
af70: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
af80: 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 0a  o Multi-thread..
af90: 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32 36 7d 20 41  **.** {H14126} A
afa0: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
afb0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
afc0: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
afd0: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 29  FIG_SERIALIZED])
afe0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61  .**          sha
aff0: 6c 6c 20 73 65 74 20 74 68 65 20 64 65 66 61 75  ll set the defau
b000: 6c 74 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  lt [threading mo
b010: 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65  de] to Serialize
b020: 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 32 39  d..**.** {H14129
b030: 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
b040: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
b050: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
b060: 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2c 58 29  CONFIG_MUTEX],X)
b070: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65  .**          whe
b080: 72 65 20 58 20 69 73 20 61 20 70 6f 69 6e 74 65  re X is a pointe
b090: 72 20 74 6f 20 61 6e 20 69 6e 69 74 69 61 6c 69  r to an initiali
b0a0: 7a 65 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  zed [sqlite3_mut
b0b0: 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 20  ex_methods].**  
b0c0: 20 20 20 20 20 20 20 20 6f 62 6a 65 63 74 20 73          object s
b0d0: 68 61 6c 6c 20 63 61 75 73 65 20 61 6c 6c 20 73  hall cause all s
b0e0: 75 62 73 65 71 75 65 6e 74 20 6d 75 74 65 78 20  ubsequent mutex 
b0f0: 6f 70 65 72 61 74 69 6f 6e 73 20 70 65 72 66 6f  operations perfo
b100: 72 6d 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rmed.**         
b110: 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 75 73   by SQLite to us
b120: 65 20 74 68 65 20 6d 75 74 65 78 20 6d 65 74 68  e the mutex meth
b130: 6f 64 73 20 74 68 61 74 20 77 65 72 65 20 70 72  ods that were pr
b140: 65 73 65 6e 74 20 69 6e 20 58 0a 2a 2a 20 20 20  esent in X.**   
b150: 20 20 20 20 20 20 20 64 75 72 69 6e 67 20 74 68         during th
b160: 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  e call to [sqlit
b170: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
b180: 0a 2a 2a 20 7b 48 31 34 31 33 32 7d 20 41 20 73  .** {H14132} A s
b190: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
b1a0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
b1b0: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
b1c0: 47 5f 47 45 54 4d 55 54 45 58 5d 2c 58 29 0a 2a  G_GETMUTEX],X).*
b1d0: 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72 65  *          where
b1e0: 20 58 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20   X is a pointer 
b1f0: 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d  to an [sqlite3_m
b200: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  utex_methods] ob
b210: 6a 65 63 74 20 0a 2a 2a 20 20 20 20 20 20 20 20  ject .**        
b220: 20 20 73 68 61 6c 6c 20 6f 76 65 72 77 72 69 74    shall overwrit
b230: 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
b240: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
b250: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 0a  methods] object.
b260: 2a 2a 20 20 20 20 20 20 20 20 20 20 77 69 74 68  **          with
b270: 20 74 68 65 20 6d 75 74 65 78 20 6d 65 74 68 6f   the mutex metho
b280: 64 73 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20  ds currently in 
b290: 75 73 65 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  use by SQLite..*
b2a0: 2a 0a 2a 2a 20 7b 48 31 34 31 33 35 7d 20 41 20  *.** {H14135} A 
b2b0: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
b2c0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
b2d0: 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
b2e0: 49 47 5f 4d 41 4c 4c 4f 43 5d 2c 4d 29 0a 2a 2a  IG_MALLOC],M).**
b2f0: 20 20 20 20 20 20 20 20 20 20 77 68 65 72 65 20            where 
b300: 4d 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  M is a pointer t
b310: 6f 20 61 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64  o an initialized
b320: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
b330: 74 68 6f 64 73 5d 0a 2a 2a 20 20 20 20 20 20 20  thods].**       
b340: 20 20 20 6f 62 6a 65 63 74 20 73 68 61 6c 6c 20     object shall 
b350: 63 61 75 73 65 20 61 6c 6c 20 73 75 62 73 65 71  cause all subseq
b360: 75 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  uent memory allo
b370: 63 61 74 69 6f 6e 20 6f 70 65 72 61 74 69 6f 6e  cation operation
b380: 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 65  s.**          pe
b390: 72 66 6f 72 6d 65 64 20 62 79 20 53 51 4c 69 74  rformed by SQLit
b3a0: 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 74  e to use the met
b3b0: 68 6f 64 73 20 74 68 61 74 20 77 65 72 65 20 70  hods that were p
b3c0: 72 65 73 65 6e 74 20 69 6e 20 0a 2a 2a 20 20 20  resent in .**   
b3d0: 20 20 20 20 20 20 20 4d 20 64 75 72 69 6e 67 20         M during 
b3e0: 74 68 65 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  the call to [sql
b3f0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a  ite3_config()]..
b400: 2a 2a 0a 2a 2a 20 7b 48 31 34 31 33 38 7d 20 41  **.** {H14138} A
b410: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
b420: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
b430: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
b440: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2c 4d  FIG_GETMALLOC],M
b450: 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68  ).**          wh
b460: 65 72 65 20 4d 20 69 73 20 61 20 70 6f 69 6e 74  ere M is a point
b470: 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65  er to an [sqlite
b480: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 6f  3_mem_methods] o
b490: 62 6a 65 63 74 20 73 68 61 6c 6c 0a 2a 2a 20 20  bject shall.**  
b4a0: 20 20 20 20 20 20 20 20 6f 76 65 72 77 72 69 74          overwrit
b4b0: 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
b4c0: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
b4d0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 77 69  thods] object wi
b4e0: 74 68 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  th .**          
b4f0: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
b500: 61 74 69 6f 6e 20 6d 65 74 68 6f 64 73 20 63 75  ation methods cu
b510: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 20 62  rrently in use b
b520: 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  y.**          SQ
b530: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34  Lite..**.** {H14
b540: 31 34 31 7d 20 41 20 73 75 63 63 65 73 73 66 75  141} A successfu
b550: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
b560: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
b570: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
b580: 54 55 53 5d 2c 31 29 0a 2a 2a 20 20 20 20 20 20  TUS],1).**      
b590: 20 20 20 20 73 68 61 6c 6c 20 65 6e 61 62 6c 65      shall enable
b5a0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
b5b0: 63 61 74 69 6f 6e 20 73 74 61 74 75 73 20 63 6f  cation status co
b5c0: 6c 6c 65 63 74 69 6f 6e 20 6c 6f 67 69 63 2e 0a  llection logic..
b5d0: 2a 2a 0a 2a 2a 20 7b 48 31 34 31 34 34 7d 20 41  **.** {H14144} A
b5e0: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
b5f0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
b600: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
b610: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 2c 30  FIG_MEMSTATUS],0
b620: 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  ).**          sh
b630: 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68 65 20  all disable the 
b640: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b650: 6e 20 73 74 61 74 75 73 20 63 6f 6c 6c 65 63 74  n status collect
b660: 69 6f 6e 20 6c 6f 67 69 63 2e 0a 2a 2a 0a 2a 2a  ion logic..**.**
b670: 20 7b 48 31 34 31 34 37 7d 20 54 68 65 20 6d 65   {H14147} The me
b680: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
b690: 73 74 61 74 75 73 20 63 6f 6c 6c 65 63 74 69 6f  status collectio
b6a0: 6e 20 6c 6f 67 69 63 20 73 68 61 6c 6c 20 62 65  n logic shall be
b6b0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 65 6e 61  .**          ena
b6c0: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
b6d0: 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 35 30 7d 20  .**.** {H14150} 
b6e0: 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  A successful cal
b6f0: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
b700: 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
b710: 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 2c 53 2c  NFIG_SCRATCH],S,
b720: 5a 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20 20  Z,N).**         
b730: 20 77 68 65 72 65 20 5a 20 61 6e 64 20 4e 20 61   where Z and N a
b740: 72 65 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20  re non-negative 
b750: 69 6e 74 65 67 65 72 73 20 61 6e 64 20 0a 2a 2a  integers and .**
b760: 20 20 20 20 20 20 20 20 20 20 53 20 69 73 20 61            S is a
b770: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
b780: 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
b790: 66 66 65 72 20 6e 6f 74 20 6c 65 73 73 20 74 68  ffer not less th
b7a0: 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5a  an.**          Z
b7b0: 2a 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  *N bytes in size
b7c0: 20 73 68 61 6c 6c 20 63 61 75 73 65 20 53 20 74   shall cause S t
b7d0: 6f 20 62 65 20 75 73 65 64 20 62 79 20 74 68 65  o be used by the
b7e0: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 63  .**          [sc
b7f0: 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c  ratch memory all
b800: 6f 63 61 74 6f 72 5d 20 66 6f 72 20 61 73 20 6d  ocator] for as m
b810: 61 6e 79 20 61 73 20 4e 20 73 69 6d 75 6c 61 74  any as N simulat
b820: 61 6e 65 6f 75 73 0a 2a 2a 20 20 20 20 20 20 20  aneous.**       
b830: 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 65     allocations e
b840: 61 63 68 20 6f 66 20 73 69 7a 65 20 28 5a 20 26  ach of size (Z &
b850: 20 7e 37 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34   ~7)..**.** {H14
b860: 31 35 33 7d 20 41 20 73 75 63 63 65 73 73 66 75  153} A successfu
b870: 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
b880: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
b890: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
b8a0: 48 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20 20 20  H],S,Z,N).**    
b8b0: 20 20 20 20 20 20 77 68 65 72 65 20 53 20 69 73        where S is
b8c0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
b8d0: 73 68 61 6c 6c 20 64 69 73 61 62 6c 65 20 74 68  shall disable th
b8e0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
b8f0: 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 61 6c  cratch memory al
b900: 6c 6f 63 61 74 6f 72 5d 2e 0a 2a 2a 0a 2a 2a 20  locator]..**.** 
b910: 7b 48 31 34 31 35 36 7d 20 41 20 73 75 63 63 65  {H14156} A succe
b920: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ssful call to.**
b930: 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
b940: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
b950: 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
b960: 43 48 45 5d 2c 53 2c 5a 2c 4e 29 0a 2a 2a 20 20  CHE],S,Z,N).**  
b970: 20 20 20 20 20 20 20 20 77 68 65 72 65 20 5a 20          where Z 
b980: 61 6e 64 20 4e 20 61 72 65 20 6e 6f 6e 2d 6e 65  and N are non-ne
b990: 67 61 74 69 76 65 20 69 6e 74 65 67 65 72 73 20  gative integers 
b9a0: 61 6e 64 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  and .**         
b9b0: 20 53 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20   S is a pointer 
b9c0: 74 6f 20 61 6e 20 61 6c 69 67 6e 65 64 20 6d 65  to an aligned me
b9d0: 6d 6f 72 79 20 62 75 66 66 65 72 20 6e 6f 74 20  mory buffer not 
b9e0: 6c 65 73 73 20 74 68 61 6e 0a 2a 2a 20 20 20 20  less than.**    
b9f0: 20 20 20 20 20 20 5a 2a 4e 20 62 79 74 65 73 20        Z*N bytes 
ba00: 69 6e 20 73 69 7a 65 20 73 68 61 6c 6c 20 63 61  in size shall ca
ba10: 75 73 65 20 53 20 74 6f 20 62 65 20 75 73 65 64  use S to be used
ba20: 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   by the.**      
ba30: 20 20 20 20 5b 70 61 67 65 63 61 63 68 65 20 6d      [pagecache m
ba40: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
ba50: 20 66 6f 72 20 61 73 20 6d 61 6e 79 20 61 73 20   for as many as 
ba60: 4e 20 73 69 6d 75 6c 61 74 61 6e 65 6f 75 73 0a  N simulataneous.
ba70: 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6c 6c 6f  **          allo
ba80: 63 61 74 69 6f 6e 73 20 65 61 63 68 20 6f 66 20  cations each of 
ba90: 73 69 7a 65 20 28 5a 20 26 20 7e 37 29 2e 0a 2a  size (Z & ~7)..*
baa0: 2a 0a 2a 2a 20 7b 48 31 34 31 35 39 7d 20 41 20  *.** {H14159} A 
bab0: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
bac0: 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
bad0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
bae0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
baf0: 41 47 45 43 41 43 48 45 5d 2c 53 2c 5a 2c 4e 29  AGECACHE],S,Z,N)
bb00: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65  .**          whe
bb10: 72 65 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  re S is a NULL p
bb20: 6f 69 6e 74 65 72 20 73 68 61 6c 6c 20 64 69 73  ointer shall dis
bb30: 61 62 6c 65 20 74 68 65 0a 2a 2a 20 20 20 20 20  able the.**     
bb40: 20 20 20 20 20 5b 70 61 67 65 63 61 63 68 65 20       [pagecache 
bb50: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
bb60: 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 31 36 32  ]..**.** {H14162
bb70: 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63  } A successful c
bb80: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
bb90: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
bba0: 43 4f 4e 46 49 47 5f 48 45 41 50 5d 2c 48 2c 5a  CONFIG_HEAP],H,Z
bbb0: 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ,N).**          
bbc0: 77 68 65 72 65 20 5a 20 61 6e 64 20 4e 20 61 72  where Z and N ar
bbd0: 65 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 69  e non-negative i
bbe0: 6e 74 65 67 65 72 73 20 61 6e 64 20 0a 2a 2a 20  ntegers and .** 
bbf0: 20 20 20 20 20 20 20 20 20 48 20 69 73 20 61 20           H is a 
bc00: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 6c  pointer to an al
bc10: 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
bc20: 66 65 72 20 6e 6f 74 20 6c 65 73 73 20 74 68 61  fer not less tha
bc30: 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5a 20  n.**          Z 
bc40: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 73 68  bytes in size sh
bc50: 61 6c 6c 20 65 6e 61 62 6c 65 20 74 68 65 20 5b  all enable the [
bc60: 6d 65 6d 73 79 73 35 5d 20 6d 65 6d 6f 72 79 20  memsys5] memory 
bc70: 61 6c 6c 6f 63 61 74 6f 72 0a 2a 2a 20 20 20 20  allocator.**    
bc80: 20 20 20 20 20 20 61 6e 64 20 63 61 75 73 65 20        and cause 
bc90: 69 74 20 74 6f 20 75 73 65 20 62 75 66 66 65 72  it to use buffer
bca0: 20 53 20 61 73 20 69 74 73 20 6d 65 6d 6f 72 79   S as its memory
bcb0: 20 73 6f 75 72 63 65 20 61 6e 64 20 74 6f 20 75   source and to u
bcc0: 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  se.**          a
bcd0: 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
bce0: 69 6f 6e 20 73 69 7a 65 20 6f 66 20 4e 2e 0a 2a  ion size of N..*
bcf0: 2a 0a 2a 2a 20 7b 48 31 34 31 36 35 7d 20 41 20  *.** {H14165} A 
bd00: 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
bd10: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
bd20: 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
bd30: 49 47 5f 48 45 41 50 5d 2c 48 2c 5a 2c 4e 29 0a  IG_HEAP],H,Z,N).
bd40: 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 72  **          wher
bd50: 65 20 48 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  e H is a NULL po
bd60: 69 6e 74 65 72 20 73 68 61 6c 6c 20 64 69 73 61  inter shall disa
bd70: 62 6c 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ble the.**      
bd80: 20 20 20 20 5b 6d 65 6d 73 79 73 35 5d 20 6d 65      [memsys5] me
bd90: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 0a  mory allocator..
bda0: 2a 2a 0a 2a 2a 20 7b 48 31 34 31 36 38 7d 20 41  **.** {H14168} A
bdb0: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
bdc0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
bdd0: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
bde0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 5a  FIG_LOOKASIDE],Z
bdf0: 2c 4e 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ,N).**          
be00: 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20  shall cause the 
be10: 64 65 66 61 75 6c 74 20 5b 6c 6f 6f 6b 61 73 69  default [lookasi
be20: 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
be30: 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
be40: 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  on.**          f
be50: 6f 72 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65  or new [database
be60: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 74 6f   connections] to
be70: 20 62 65 20 4e 20 73 6c 6f 74 73 20 6f 66 20 5a   be N slots of Z
be80: 20 62 79 74 65 73 20 65 61 63 68 2e 0a 2a 2f 0a   bytes each..*/.
be90: 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
bea0: 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TAL int sqlite3_
beb0: 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29  config(int, ...)
bec0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
bed0: 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74  F: Configure dat
bee0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bef0: 73 20 20 7b 48 31 34 32 30 30 7d 20 3c 53 32 30  s  {H14200} <S20
bf00: 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  000>.** EXPERIME
bf10: 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  NTAL.**.** The s
bf20: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
bf30: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
bf40: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
bf50: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
bf60: 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
bf70: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
bf80: 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
bf90: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
bfa0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
bfb0: 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
bfc0: 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
bfd0: 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
bfe0: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
bff0: 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
c000: 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
c010: 61 72 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a  argument).  The.
c020: 2a 2a 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  ** sqlite3_db_co
c030: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
c040: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
c050: 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66  d immediately af
c060: 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ter.** the datab
c070: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
c080: 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  s created using 
c090: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
c0a0: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ,.** [sqlite3_op
c0b0: 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c  en16()], or [sql
c0c0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
c0d0: 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63    .**.** The sec
c0e0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
c0f0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
c100: 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
c110: 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  he.** configurat
c120: 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69 6e  ion verb - an in
c130: 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
c140: 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a 2a  indicates what.*
c150: 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  * aspect of the 
c160: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c170: 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
c180: 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68  onfigured..** Th
c190: 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f  e only choice fo
c1a0: 72 20 74 68 69 73 20 76 61 6c 75 65 20 69 73 20  r this value is 
c1b0: 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
c1c0: 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20  _LOOKASIDE]..** 
c1d0: 4e 65 77 20 76 65 72 62 73 20 61 72 65 20 6c 69  New verbs are li
c1e0: 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65 64  kely to be added
c1f0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
c200: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
c210: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  * Additional arg
c220: 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e  uments depend on
c230: 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a   the verb..**.**
c240: 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
c250: 2a 2a 20 7b 48 31 34 32 30 33 7d 20 41 20 63 61  ** {H14203} A ca
c260: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  ll to [sqlite3_d
c270: 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e  b_config(D,V,...
c280: 29 5d 20 73 68 61 6c 6c 20 72 65 74 75 72 6e 20  )] shall return 
c290: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 20  [SQLITE_OK].**  
c2a0: 20 20 20 20 20 20 20 20 69 66 20 61 6e 64 20 6f          if and o
c2b0: 6e 6c 79 20 69 66 20 74 68 65 20 63 61 6c 6c 20  nly if the call 
c2c0: 69 73 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a  is successful..*
c2d0: 2a 0a 2a 2a 20 7b 48 31 34 32 30 36 7d 20 49 66  *.** {H14206} If
c2e0: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 6c 6f   one or more slo
c2f0: 74 73 20 6f 66 20 74 68 65 20 5b 6c 6f 6f 6b 61  ts of the [looka
c300: 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
c310: 63 61 74 6f 72 5d 20 66 6f 72 0a 2a 2a 20 20 20  cator] for.**   
c320: 20 20 20 20 20 20 20 5b 64 61 74 61 62 61 73 65         [database
c330: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 61   connection] D a
c340: 72 65 20 69 6e 20 75 73 65 2c 20 74 68 65 6e 20  re in use, then 
c350: 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 20 20 20  a call to.**    
c360: 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 64        [sqlite3_d
c370: 62 5f 63 6f 6e 66 69 67 5d 28 44 2c 5b 53 51 4c  b_config](D,[SQL
c380: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
c390: 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 73 68 61  KASIDE],...) sha
c3a0: 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  ll.**          f
c3b0: 61 69 6c 20 77 69 74 68 20 61 6e 20 5b 53 51 4c  ail with an [SQL
c3c0: 49 54 45 5f 42 55 53 59 5d 20 72 65 74 75 72 6e  ITE_BUSY] return
c3d0: 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   code..**.** {H1
c3e0: 34 32 30 39 7d 20 41 20 73 75 63 63 65 73 73 66  4209} A successf
c3f0: 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 20  ul call to .**  
c400: 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
c410: 5f 64 62 5f 63 6f 6e 66 69 67 5d 28 44 2c 5b 53  _db_config](D,[S
c420: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
c430: 4f 4f 4b 41 53 49 44 45 5d 2c 42 2c 5a 2c 4e 29  OOKASIDE],B,Z,N)
c440: 20 77 68 65 72 65 0a 2a 2a 20 20 20 20 20 20 20   where.**       
c450: 20 20 20 44 20 69 73 20 61 6e 20 6f 70 65 6e 20     D is an open 
c460: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c470: 74 69 6f 6e 5d 20 61 6e 64 20 5a 20 61 6e 64 20  tion] and Z and 
c480: 4e 20 61 72 65 20 70 6f 73 69 74 69 76 65 0a 2a  N are positive.*
c490: 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 67  *          integ
c4a0: 65 72 73 20 61 6e 64 20 42 20 69 73 20 61 6e 20  ers and B is an 
c4b0: 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 20 61  aligned buffer a
c4c0: 74 20 6c 65 61 73 74 20 5a 2a 4e 20 62 79 74 65  t least Z*N byte
c4d0: 73 20 69 6e 20 73 69 7a 65 0a 2a 2a 20 20 20 20  s in size.**    
c4e0: 20 20 20 20 20 20 73 68 61 6c 6c 20 63 61 75 73        shall caus
c4f0: 65 20 74 68 65 20 5b 6c 6f 6f 6b 61 73 69 64 65  e the [lookaside
c500: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
c510: 72 5d 20 66 6f 72 20 44 20 74 6f 20 75 73 65 20  r] for D to use 
c520: 62 75 66 66 65 72 20 42 20 0a 2a 2a 20 20 20 20  buffer B .**    
c530: 20 20 20 20 20 20 77 69 74 68 20 4e 20 73 6c 6f        with N slo
c540: 74 73 20 6f 66 20 5a 20 62 79 74 65 73 20 65 61  ts of Z bytes ea
c550: 63 68 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 34 32 31  ch..**.** {H1421
c560: 32 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20  2} A successful 
c570: 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 20 20 20 20  call to .**     
c580: 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 64 62       [sqlite3_db
c590: 5f 63 6f 6e 66 69 67 5d 28 44 2c 5b 53 51 4c 49  _config](D,[SQLI
c5a0: 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
c5b0: 41 53 49 44 45 5d 2c 42 2c 5a 2c 4e 29 20 77 68  ASIDE],B,Z,N) wh
c5c0: 65 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ere.**          
c5d0: 44 20 69 73 20 61 6e 20 6f 70 65 6e 20 5b 64 61  D is an open [da
c5e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
c5f0: 6e 5d 20 61 6e 64 20 5a 20 61 6e 64 20 4e 20 61  n] and Z and N a
c600: 72 65 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 20  re positive.**  
c610: 20 20 20 20 20 20 20 20 69 6e 74 65 67 65 72 73          integers
c620: 20 61 6e 64 20 42 20 69 73 20 4e 55 4c 4c 20 70   and B is NULL p
c630: 6f 69 6e 74 65 72 20 73 68 61 6c 6c 20 63 61 75  ointer shall cau
c640: 73 65 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  se the.**       
c650: 20 20 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65     [lookaside me
c660: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
c670: 66 6f 72 20 44 20 74 6f 20 61 20 6f 62 74 61 69  for D to a obtai
c680: 6e 20 5a 2a 4e 20 62 79 74 65 20 62 75 66 66 65  n Z*N byte buffe
c690: 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 72  r.**          fr
c6a0: 6f 6d 20 74 68 65 20 70 72 69 6d 61 72 79 20 6d  om the primary m
c6b0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
c6c0: 61 6e 64 20 75 73 65 20 74 68 61 74 20 62 75 66  and use that buf
c6d0: 66 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  fer.**          
c6e0: 77 69 74 68 20 4e 20 6c 6f 6f 6b 61 73 69 64 65  with N lookaside
c6f0: 20 73 6c 6f 74 73 20 6f 66 20 5a 20 62 79 74 65   slots of Z byte
c700: 73 20 65 61 63 68 2e 0a 2a 2a 0a 2a 2a 20 7b 48  s each..**.** {H
c710: 31 34 32 31 35 7d 20 41 20 73 75 63 63 65 73 73  14215} A success
c720: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20  ful call to .** 
c730: 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
c740: 33 5f 64 62 5f 63 6f 6e 66 69 67 5d 28 44 2c 5b  3_db_config](D,[
c750: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
c760: 4c 4f 4f 4b 41 53 49 44 45 5d 2c 42 2c 5a 2c 4e  LOOKASIDE],B,Z,N
c770: 29 20 77 68 65 72 65 0a 2a 2a 20 20 20 20 20 20  ) where.**      
c780: 20 20 20 20 44 20 69 73 20 61 6e 20 6f 70 65 6e      D is an open
c790: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
c7a0: 63 74 69 6f 6e 5d 20 61 6e 64 20 5a 20 61 6e 64  ction] and Z and
c7b0: 20 4e 20 61 72 65 20 7a 65 72 6f 20 73 68 61 6c   N are zero shal
c7c0: 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 69  l.**          di
c7d0: 73 61 62 6c 65 20 74 68 65 20 5b 6c 6f 6f 6b 61  sable the [looka
c7e0: 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
c7f0: 63 61 74 6f 72 5d 20 66 6f 72 20 44 2e 0a 2a 2a  cator] for D..**
c800: 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  .**.*/.SQLITE_EX
c810: 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73  PERIMENTAL int s
c820: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
c830: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
c840: 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  p, ...);../*.** 
c850: 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
c860: 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74   Allocation Rout
c870: 69 6e 65 73 20 7b 48 31 30 31 35 35 7d 20 3c 53  ines {H10155} <S
c880: 32 30 31 32 30 3e 0a 2a 2a 20 45 58 50 45 52 49  20120>.** EXPERI
c890: 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20  MENTAL.**.** An 
c8a0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
c8b0: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
c8c0: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
c8d0: 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
c8e0: 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
c8f0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c900: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
c910: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
c920: 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
c930: 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
c940: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
c950: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
c960: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
c970: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
c980: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
c990: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
c9a0: 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
c9b0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
c9c0: 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
c9d0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20  ONFIG_MALLOC].  
c9e0: 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69  By creating an i
c9f0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
ca00: 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61  object.** and pa
ca10: 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
ca20: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 64  ite3_config()] d
ca30: 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  uring configurat
ca40: 69 6f 6e 2c 20 61 6e 0a 2a 2a 20 61 70 70 6c 69  ion, an.** appli
ca50: 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
ca60: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
ca70: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
ca80: 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 0a 2a 2a  ion subsystem.**
ca90: 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
caa0: 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
cab0: 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
cac0: 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   needs..**.** No
cad0: 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  te that SQLite c
cae0: 6f 6d 65 73 20 77 69 74 68 20 61 20 62 75 69 6c  omes with a buil
caf0: 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
cb00: 63 61 74 6f 72 20 74 68 61 74 20 69 73 0a 2a 2a  cator that is.**
cb10: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
cb20: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
cb30: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
cb40: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
cb50: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
cb60: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
cb70: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
cb80: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
cb90: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
cba0: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
cbb0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
cbc0: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
cbd0: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
cbe0: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
cbf0: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
cc00: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
cc10: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
cc20: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
cc30: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
cc40: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
cc50: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
cc60: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
cc70: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
cc80: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
cc90: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
cca0: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
ccb0: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
ccc0: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 46   The xMalloc, xF
ccd0: 72 65 65 2c 20 61 6e 64 20 78 52 65 61 6c 6c 6f  ree, and xReallo
cce0: 63 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  c methods must w
ccf0: 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
cd00: 6d 61 6c 6c 6f 63 28 29 2c 20 66 72 65 65 28 29  malloc(), free()
cd10: 2c 20 61 6e 64 20 72 65 61 6c 6c 6f 63 28 29 20  , and realloc() 
cd20: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
cd30: 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72  he standard libr
cd40: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  ary..**.** xSize
cd50: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
cd60: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
cd70: 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
cd80: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
cd90: 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
cda0: 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
cdb0: 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
cdc0: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
cdd0: 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
cde0: 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
cdf0: 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
ce00: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
ce10: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
ce20: 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
ce30: 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
ce40: 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
ce50: 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
ce60: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
ce70: 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
ce80: 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
ce90: 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
cea0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
ceb0: 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
cec0: 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
ced0: 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
cee0: 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
cef0: 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
cf00: 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
cf10: 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
cf20: 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
cf30: 66 20 32 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  f 2..**.** The x
cf40: 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74  Init method init
cf50: 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f  ializes the memo
cf60: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28  ry allocator.  (
cf70: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
cf80: 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
cf90: 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
cfa0: 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
cfb0: 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
cfc0: 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
cfd0: 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
cfe0: 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
cff0: 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
d000: 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
d010: 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
d020: 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
d030: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
d040: 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
d050: 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
d060: 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
d070: 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
d080: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
d090: 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
d0a0: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
d0b0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
d0c0: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
d0d0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
d0e0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
d0f0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
d100: 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
d110: 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
d120: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
d130: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
d140: 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
d150: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
d160: 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
d170: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
d180: 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
d190: 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
d1a0: 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
d1b0: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
d1c0: 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
d1d0: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
d1e0: 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
d1f0: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
d200: 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
d210: 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
d220: 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
d230: 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
d240: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
d250: 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
d260: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
d270: 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
d280: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
d290: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
d2a0: 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
d2b0: 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
d2c0: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
d2d0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
d2e0: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
d2f0: 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
d300: 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
d310: 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
d320: 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
d330: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
d340: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
d350: 69 6f 6e 73 20 7b 48 31 30 31 36 30 7d 20 3c 53  ions {H10160} <S
d360: 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  20000>.** EXPERI
d370: 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65  MENTAL.**.** The
d380: 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
d390: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
d3a0: 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
d3b0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
d3c0: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
d3d0: 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
d3e0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
d3f0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
d400: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
d410: 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
d420: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
d430: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
d440: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
d450: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
d460: 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
d470: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
d480: 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
d490: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
d4a0: 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
d4b0: 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
d4c0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
d4d0: 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
d4e0: 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
d4f0: 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
d500: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
d510: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
d520: 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
d530: 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
d540: 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
d550: 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
d560: 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
d570: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
d580: 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
d590: 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
d5a0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
d5b0: 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
d5c0: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
d5d0: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
d5e0: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69  his option.  Thi
d5f0: 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65  s option disable
d600: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
d610: 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
d620: 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
d630: 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
d640: 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
d650: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 3c 2f  single thread.</
d660: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
d670: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
d680: 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
d690: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
d6a0: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
d6b0: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54 68 69 73  is option.  This
d6c0: 20 6f 70 74 69 6f 6e 20 64 69 73 61 62 6c 65 73   option disables
d6d0: 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
d6e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
d6f0: 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
d700: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
d710: 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
d720: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
d730: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
d740: 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
d750: 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
d760: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
d770: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
d780: 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
d790: 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
d7a0: 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
d7b0: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
d7c0: 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
d7d0: 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
d7e0: 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
d7f0: 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
d800: 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
d810: 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
d820: 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
d830: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
d840: 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 53  he same time.  S
d850: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
d860: 67 20 6d 6f 64 65 5d 0a 2a 2a 20 64 6f 63 75 6d  g mode].** docum
d870: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
d880: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
d890: 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
d8a0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
d8b0: 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74  G_SERIALIZED</dt
d8c0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
d8d0: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
d8e0: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
d8f0: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   This option ena
d900: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
d910: 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
d920: 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
d930: 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
d940: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
d950: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
d960: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
d970: 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
d980: 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
d990: 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
d9a0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
d9b0: 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
d9c0: 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
d9d0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
d9e0: 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
d9f0: 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
da00: 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
da10: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
da20: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
da30: 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
da40: 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
da50: 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
da60: 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
da70: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
da80: 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
da90: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
daa0: 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
dab0: 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
dac0: 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 53 65 65  ame time..** See
dad0: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
dae0: 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74  mode] documentat
daf0: 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
db00: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 3c  al information.<
db10: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
db20: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
db30: 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
db40: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
db50: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
db60: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
db70: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
db80: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
db90: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
dba0: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
dbb0: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
dbc0: 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
dbd0: 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
dbe0: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
dbf0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
dc00: 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
dc10: 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
dc20: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
dc30: 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
dc40: 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a   SQLite.</dd>.**
dc50: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
dc60: 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c  ONFIG_GETMALLOC<
dc70: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
dc80: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
dc90: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
dca0: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
dcb0: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
dcc0: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
dcd0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
dce0: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
dcf0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
dd00: 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
dd10: 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
dd20: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
dd30: 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
dd40: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
dd50: 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73 20 6f 70  ines..** This op
dd60: 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
dd70: 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
dd80: 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
dd90: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
dda0: 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
ddb0: 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c  apper that simul
ddc0: 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c  ations memory al
ddd0: 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
dde0: 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65   or.** tracks me
ddf0: 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20  mory usage, for 
de00: 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e 0a 2a 2a  example.</dd>.**
de10: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
de20: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
de30: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  /dt>.** <dd>This
de40: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
de50: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
de60: 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
de70: 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
de80: 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
de90: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
dea0: 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
deb0: 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
dec0: 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
ded0: 73 74 69 63 73 2e 20 57 68 65 6e 20 64 69 73 61  stics. When disa
dee0: 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77  bled, the follow
def0: 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
df00: 66 61 63 65 73 20 62 65 63 6f 6d 65 20 0a 2a 2a  faces become .**
df10: 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
df20: 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
df30: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
df40: 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
df50: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
df60: 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
df70: 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
df80: 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
df90: 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20  p_limit()].**   
dfa0: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
dfb0: 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  atus()].**   </u
dfc0: 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  l>.** </dd>.**.*
dfd0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
dfe0: 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
dff0: 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
e000: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
e010: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
e020: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
e030: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
e040: 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
e050: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
e060: 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70   arguments:  A p
e070: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
e080: 6d 6f 72 79 2c 20 74 68 65 0a 2a 2a 20 73 69 7a  mory, the.** siz
e090: 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63  e of each scratc
e0a0: 68 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61  h buffer (sz), a
e0b0: 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
e0c0: 20 62 75 66 66 65 72 73 20 28 4e 29 2e 20 20 54   buffers (N).  T
e0d0: 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e  he sz.** argumen
e0e0: 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74  t must be a mult
e0f0: 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68 65 20  iple of 16. The 
e100: 73 7a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f  sz parameter sho
e110: 75 6c 64 20 62 65 20 61 20 66 65 77 20 62 79 74  uld be a few byt
e120: 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74 68 61  es.** larger tha
e130: 6e 20 74 68 65 20 61 63 74 75 61 6c 20 73 63 72  n the actual scr
e140: 61 74 63 68 20 73 70 61 63 65 20 72 65 71 75 69  atch space requi
e150: 72 65 64 20 64 75 65 20 69 6e 74 65 72 6e 61 6c  red due internal
e160: 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68   overhead..** Th
e170: 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d  e first.** argum
e180: 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74  ent should point
e190: 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   to an allocatio
e1a0: 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  n of at least sz
e1b0: 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
e1c0: 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  ry..** SQLite wi
e1d0: 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74  ll use no more t
e1e0: 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20  han one scratch 
e1f0: 62 75 66 66 65 72 20 61 74 20 6f 6e 63 65 20 70  buffer at once p
e200: 65 72 20 74 68 72 65 61 64 2c 20 73 6f 0a 2a 2a  er thread, so.**
e210: 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74   N should be set
e220: 20 74 6f 20 74 68 65 20 65 78 70 65 63 74 65 64   to the expected
e230: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
e240: 6f 66 20 74 68 72 65 61 64 73 2e 20 20 54 68 65  of threads.  The
e250: 20 73 7a 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72   sz.** parameter
e260: 20 73 68 6f 75 6c 64 20 62 65 20 36 20 74 69 6d   should be 6 tim
e270: 65 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  es the size of t
e280: 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
e290: 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a  ase page size..*
e2a0: 2a 20 53 63 72 61 74 63 68 20 62 75 66 66 65 72  * Scratch buffer
e2b0: 73 20 61 72 65 20 75 73 65 64 20 61 73 20 70 61  s are used as pa
e2c0: 72 74 20 6f 66 20 74 68 65 20 62 74 72 65 65 20  rt of the btree 
e2d0: 62 61 6c 61 6e 63 65 20 6f 70 65 72 61 74 69 6f  balance operatio
e2e0: 6e 2e 20 20 49 66 0a 2a 2a 20 54 68 65 20 62 74  n.  If.** The bt
e2f0: 72 65 65 20 62 61 6c 61 6e 63 65 72 20 6e 65 65  ree balancer nee
e300: 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 20 6d 65  ds additional me
e310: 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74  mory beyond what
e320: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 0a   is provided by.
e330: 2a 2a 20 73 63 72 61 74 63 68 20 62 75 66 66 65  ** scratch buffe
e340: 72 73 20 6f 72 20 69 66 20 6e 6f 20 73 63 72 61  rs or if no scra
e350: 74 63 68 20 62 75 66 66 65 72 20 73 70 61 63 65  tch buffer space
e360: 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
e370: 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6f  hen SQLite.** go
e380: 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
e390: 61 6c 6c 6f 63 28 29 5d 20 74 6f 20 6f 62 74 61  alloc()] to obta
e3a0: 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 74  in the memory it
e3b0: 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a   needs.</dd>.**.
e3c0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
e3d0: 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
e3e0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
e3f0: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
e400: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
e410: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
e420: 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
e430: 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
e440: 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20  page cache with 
e450: 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65  the default page
e460: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61   cache implemena
e470: 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20  tion.  .** This 
e480: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68  configuration sh
e490: 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
e4a0: 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
e4b0: 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a  on-define page.*
e4c0: 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
e4d0: 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64  tation is loaded
e4e0: 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54   using the SQLIT
e4f0: 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
e500: 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65  option..** There
e510: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
e520: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
e530: 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  ion: A pointer t
e540: 6f 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c  o the.** memory,
e550: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
e560: 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73  h page buffer (s
e570: 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62  z), and the numb
e580: 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e  er of pages (N).
e590: 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
e5a0: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
e5b0: 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65  wer of two betwe
e5c0: 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38  en 512 and 32768
e5d0: 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  .  The first.** 
e5e0: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
e5f0: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f  point to an allo
e600: 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61  cation of at lea
e610: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
e620: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69   memory..** SQLi
e630: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
e640: 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
e650: 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
e660: 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
e670: 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
e680: 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
e690: 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
e6a0: 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
e6b0: 2e 20 20 49 66 20 61 64 64 69 74 69 6f 6e 61 6c  .  If additional
e6c0: 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
e6d0: 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
e6e0: 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
e6f0: 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
e700: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20  option, then.** 
e710: 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
e720: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
e730: 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 69  ] for the additi
e740: 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61  onal storage spa
e750: 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65  ce..** The imple
e760: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
e770: 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  use one or more 
e780: 6f 66 20 74 68 65 20 4e 20 62 75 66 66 65 72 73  of the N buffers
e790: 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d   to hold .** mem
e7a0: 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69  ory accounting i
e7b0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 3c 2f 64 64  nformation. </dd
e7c0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
e7d0: 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
e7e0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
e7f0: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
e800: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
e810: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
e820: 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20  ite will use.** 
e830: 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
e840: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
e850: 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62  location needs b
e860: 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
e870: 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b  ided.** for by [
e880: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
e890: 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49  RATCH] and [SQLI
e8a0: 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
e8b0: 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61  CHE]..** There a
e8c0: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
e8d0: 74 73 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  ts: A pointer to
e8e0: 20 74 68 65 20 6d 65 6d 6f 72 79 2c 20 74 68 65   the memory, the
e8f0: 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
e900: 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72  tes in the memor
e910: 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68  y buffer, and th
e920: 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
e930: 74 69 6f 6e 20 73 69 7a 65 2e 20 20 49 66 0a 2a  tion size.  If.*
e940: 2a 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * the first poin
e950: 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
e960: 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
e970: 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
e980: 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
e990: 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
e9a0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
e9b0: 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
e9c0: 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
e9d0: 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
e9e0: 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
e9f0: 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
ea00: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
ea10: 20 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72   If the.** memor
ea20: 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  y pointer is not
ea30: 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72   NULL and either
ea40: 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
ea50: 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b  MEMSYS3] or.** [
ea60: 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
ea70: 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e  MSYS5] are defin
ea80: 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ed, then the alt
ea90: 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
eaa0: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
eab0: 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
eac0: 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
ead0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
eae0: 6f 6e 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a 2a  on needs.</dd>.*
eaf0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
eb00: 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74  CONFIG_MUTEX</dt
eb10: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
eb20: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
eb30: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
eb40: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
eb50: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
eb60: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
eb70: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
eb80: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
eb90: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
eba0: 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
ebb0: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74  ve low-level mut
ebc0: 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  ex routines to b
ebd0: 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a  e used in place.
ebe0: 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75  ** the mutex rou
ebf0: 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
ec00: 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a   SQLite.</dd>.**
ec10: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
ec20: 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
ec30: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
ec40: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
ec50: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
ec60: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
ec70: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
ec80: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
ec90: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
eca0: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
ecb0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
ecc0: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
ecd0: 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
ece0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
ecf0: 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
ed00: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 0a  mutex routines..
ed10: 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
ed20: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
ed30: 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
ed40: 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
ed50: 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
ed60: 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
ed70: 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
ed80: 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
ed90: 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
eda0: 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
edb0: 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f  , for example.</
edc0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
edd0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
ede0: 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
edf0: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
ee00: 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
ee10: 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
ee20: 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20   the default.** 
ee30: 6d 65 6d 6f 72 79 20 61 6c 6c 63 61 74 69 6f 6e  memory allcation
ee40: 20 6c 6f 6f 6b 61 73 69 64 65 20 6f 70 74 69 6d   lookaside optim
ee50: 69 7a 61 74 69 6f 6e 2e 20 20 54 68 65 20 66 69  ization.  The fi
ee60: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
ee70: 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
ee80: 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
ee90: 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
eea0: 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
eeb0: 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
eec0: 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
eed0: 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
eee0: 6e 6e 65 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  nnection.</dd>.*
eef0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
ef00: 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c 2f 64  CONFIG_PCACHE</d
ef10: 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  t>.** <dd>This o
ef20: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
ef30: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
ef40: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
ef50: 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74   to.** an [sqlit
ef60: 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
ef70: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73  s] object.  This
ef80: 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
ef90: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
efa0: 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70  ** to a custom p
efb0: 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
efc0: 65 6e 74 61 74 69 6f 6e 2e 20 20 53 51 4c 69 74  entation.  SQLit
efd0: 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
efe0: 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20  f the.** object 
eff0: 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20  and uses it for 
f000: 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
f010: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f  y allocations.</
f020: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
f030: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
f040: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
f050: 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  d>This option ta
f060: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
f070: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
f080: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
f090: 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  * [sqlite3_pcach
f0a0: 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  e_methods] objec
f0b0: 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
f0c0: 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  s of the current
f0d0: 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69  .** page cache i
f0e0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
f0f0: 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 3c  to that object.<
f100: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
f110: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
f120: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
f130: 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69  THREAD  1  /* ni
f140: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
f150: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
f160: 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e  THREAD   2  /* n
f170: 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
f180: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
f190: 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20  ALIZED    3  /* 
f1a0: 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
f1b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
f1c0: 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a  LOC        4  /*
f1d0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
f1e0: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
f1f0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
f200: 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20  ETMALLOC     5  
f210: 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
f220: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
f230: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
f240: 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36  _SCRATCH       6
f250: 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
f260: 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
f270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
f280: 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20  IG_PAGECACHE    
f290: 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   7  /* void*, in
f2a0: 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
f2b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
f2c0: 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20  NFIG_HEAP       
f2d0: 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     8  /* void*, 
f2e0: 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d  int nByte, int m
f2f0: 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  in */.#define SQ
f300: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
f310: 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20  TATUS     9  /* 
f320: 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69  boolean */.#defi
f330: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
f340: 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30  _MUTEX        10
f350: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
f360: 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  ex_methods* */.#
f370: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
f380: 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20  NFIG_GETMUTEX   
f390: 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33    11  /* sqlite3
f3a0: 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
f3b0: 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79  */./* previously
f3c0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
f3d0: 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69  HUNKALLOC 12 whi
f3e0: 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64  ch is now unused
f3f0: 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51  . */ .#define SQ
f400: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
f410: 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20  ASIDE    13  /* 
f420: 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
f430: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
f440: 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34  _PCACHE       14
f450: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
f460: 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  che_methods* */.
f470: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
f480: 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20  ONFIG_GETPCACHE 
f490: 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74 65     15  /* sqlite
f4a0: 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
f4b0: 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  * */../*.** CAPI
f4c0: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
f4d0: 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30  ion Options {H10
f4e0: 31 37 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a  170} <S20000>.**
f4f0: 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
f500: 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
f510: 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
f520: 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
f530: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
f540: 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
f550: 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
f560: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
f570: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
f580: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
f590: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
f5a0: 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
f5b0: 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
f5c0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
f5d0: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
f5e0: 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
f5f0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
f600: 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
f610: 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
f620: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
f630: 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
f640: 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
f650: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
f660: 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
f670: 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
f680: 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
f690: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
f6a0: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
f6b0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
f6c0: 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
f6d0: 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
f6e0: 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
f6f0: 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
f700: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
f710: 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
f720: 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
f730: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
f740: 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
f750: 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e   <dd>This option
f760: 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
f770: 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
f780: 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
f790: 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
f7a0: 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
f7b0: 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
f7c0: 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
f7d0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f7e0: 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  ]..** The first 
f7f0: 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
f800: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
f810: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
f820: 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
f830: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
f840: 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
f850: 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
f860: 65 6d 6f 72 79 2e 20 20 54 68 65 20 66 69 72 73  emory.  The firs
f870: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 61  t.** argument ma
f880: 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
f890: 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
f8a0: 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
f8b0: 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 62 75   lookaside.** bu
f8c0: 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
f8d0: 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
f8e0: 63 28 29 5d 2e 20 20 54 68 65 20 73 65 63 6f 6e  c()].  The secon
f8f0: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
f900: 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
f910: 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
f920: 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20  er slot and the 
f930: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
f940: 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
f950: 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
f960: 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
f970: 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
f980: 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
f990: 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
f9a0: 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
f9b0: 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
f9c0: 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
f9d0: 61 72 67 75 6d 65 6e 74 73 2e 3c 2f 64 64 3e 0a  arguments.</dd>.
f9e0: 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
f9f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
fa00: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
fa10: 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69      1001  /* voi
fa20: 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a  d* int int */...
fa30: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
fa40: 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
fa50: 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  e Extended Resul
fa60: 74 20 43 6f 64 65 73 20 7b 48 31 32 32 30 30 7d  t Codes {H12200}
fa70: 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10700>.**.** 
fa80: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
fa90: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
faa0: 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
fab0: 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
fac0: 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
fad0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
fae0: 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
faf0: 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72  . The extended r
fb00: 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61  esult.** codes a
fb10: 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
fb20: 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f  efault for histo
fb30: 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
fb40: 69 74 79 20 63 6f 6e 73 69 64 65 72 61 74 69 6f  ity consideratio
fb50: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ns..**.** INVARI
fb60: 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
fb70: 32 30 31 7d 20 45 61 63 68 20 6e 65 77 20 5b 64  201} Each new [d
fb80: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
fb90: 6f 6e 5d 20 73 68 61 6c 6c 20 68 61 76 65 20 74  on] shall have t
fba0: 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  he.**          [
fbb0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
fbc0: 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 64  codes] feature d
fbd0: 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
fbe0: 6c 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 30  lt..**.** {H1220
fbf0: 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
fc00: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
fc10: 63 6f 64 65 73 28 44 2c 46 29 5d 20 69 6e 74 65  codes(D,F)] inte
fc20: 72 66 61 63 65 20 73 68 61 6c 6c 20 65 6e 61 62  rface shall enab
fc30: 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  le.**          [
fc40: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
fc50: 63 6f 64 65 73 5d 20 66 6f 72 20 74 68 65 20 20  codes] for the  
fc60: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
fc70: 74 69 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20  tion] D.**      
fc80: 20 20 20 20 69 66 20 74 68 65 20 46 20 70 61 72      if the F par
fc90: 61 6d 65 74 65 72 20 69 73 20 74 72 75 65 2c 20  ameter is true, 
fca0: 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 6d 20  or disable them 
fcb0: 69 66 20 46 20 69 73 20 66 61 6c 73 65 2e 0a 2a  if F is false..*
fcc0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
fcd0: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
fce0: 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
fcf0: 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
fd00: 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
fd10: 49 6e 73 65 72 74 20 52 6f 77 69 64 20 7b 48 31  Insert Rowid {H1
fd20: 32 32 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  2220} <S10700>.*
fd30: 2a 0a 2a 2a 20 45 61 63 68 20 65 6e 74 72 79 20  *.** Each entry 
fd40: 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62  in an SQLite tab
fd50: 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  le has a unique 
fd60: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
fd70: 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
fd80: 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
fd90: 20 22 72 6f 77 69 64 22 5d 2e 20 54 68 65 20 72   "rowid"]. The r
fda0: 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
fdb0: 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
fdc0: 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
fdd0: 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
fde0: 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
fdf0: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
fe00: 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
fe10: 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
fe20: 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
fe30: 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 49 66 0a  red columns. If.
fe40: 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
fe50: 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
fe60: 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  e [INTEGER PRIMA
fe70: 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61  RY KEY] then tha
fe80: 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
fe90: 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
fea0: 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
feb0: 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  * This routine r
fec0: 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
fed0: 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  d] of the most r
fee0: 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73  ecent.** success
fef0: 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
ff00: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
ff10: 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73  rom the [databas
ff20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
ff30: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
ff40: 67 75 6d 65 6e 74 2e 20 20 49 66 20 6e 6f 20 73  gument.  If no s
ff50: 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
ff60: 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72  T]s.** have ever
ff70: 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61   occurred on tha
ff80: 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  t database conne
ff90: 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72  ction, zero is r
ffa0: 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  eturned..**.** I
ffb0: 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
ffc0: 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
ffd0: 69 67 67 65 72 2c 20 74 68 65 6e 20 74 68 65 20  igger, then the 
ffe0: 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
fff0: 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 69  nserted.** row i
10000 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
10010 69 73 20 72 6f 75 74 69 6e 65 20 61 73 20 6c 6f  is routine as lo
10020 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65  ng as the trigge
10030 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  r is running..**
10040 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72   But once the tr
10050 69 67 67 65 72 20 74 65 72 6d 69 6e 61 74 65 73  igger terminates
10060 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
10070 72 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75  rned by this rou
10080 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72 74 73 20  tine.** reverts 
10090 74 6f 20 74 68 65 20 6c 61 73 74 20 76 61 6c 75  to the last valu
100a0 65 20 69 6e 73 65 72 74 65 64 20 62 65 66 6f 72  e inserted befor
100b0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 66 69  e the trigger fi
100c0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 49  red..**.** An [I
100d0 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c  NSERT] that fail
100e0 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
100f0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
10100 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
10110 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
10120 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
10130 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
10140 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
10150 2a 20 72 6f 75 74 69 6e 65 2e 20 20 54 68 75 73  * routine.  Thus
10160 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
10170 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
10180 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
10190 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
101a0 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
101b0 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
101c0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
101d0 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
101e0 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
101f0 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
10200 20 20 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52    When INSERT OR
10210 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f   REPLACE.** enco
10220 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61  unters a constra
10230 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69  int violation, i
10240 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e  t does not fail.
10250 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20    The.** INSERT 
10260 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
10270 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65  pletion after de
10280 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74  leting rows that
10290 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63   caused.** the c
102a0 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65  onstraint proble
102b0 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52  m so INSERT OR R
102c0 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61  EPLACE will alwa
102d0 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65  ys change.** the
102e0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
102f0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
10300 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70  .**.** For the p
10310 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
10320 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
10330 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
10340 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
10350 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
10360 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
10370 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
10380 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
10390 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 32 31 7d 20  .**.** {H12221} 
103a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  The [sqlite3_las
103b0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
103c0 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c  ] function shall
103d0 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20   return.**      
103e0 20 20 20 20 74 68 65 20 5b 72 6f 77 69 64 5d 0a      the [rowid].
103f0 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74  **          of t
10400 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  he most recent s
10410 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
10420 54 5d 20 70 65 72 66 6f 72 6d 65 64 20 6f 6e 20  T] performed on 
10430 74 68 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20  the same.**     
10440 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
10450 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 77  onnection] and w
10460 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  ithin the same o
10470 72 20 68 69 67 68 65 72 20 6c 65 76 65 6c 0a 2a  r higher level.*
10480 2a 20 20 20 20 20 20 20 20 20 20 74 72 69 67 67  *          trigg
10490 65 72 20 63 6f 6e 74 65 78 74 2c 20 6f 72 20 7a  er context, or z
104a0 65 72 6f 20 69 66 20 74 68 65 72 65 20 68 61 76  ero if there hav
104b0 65 20 62 65 65 6e 20 6e 6f 20 71 75 61 6c 69 66  e been no qualif
104c0 79 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ying.**         
104d0 20 5b 49 4e 53 45 52 54 5d 20 73 74 61 74 65 6d   [INSERT] statem
104e0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ents..**.** {H12
104f0 32 32 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  223} The [sqlite
10500 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
10510 77 69 64 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  wid()] function 
10520 73 68 61 6c 6c 20 72 65 74 75 72 6e 20 74 68 65  shall return the
10530 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 61 6d  .**          sam
10540 65 20 76 61 6c 75 65 20 77 68 65 6e 20 63 61 6c  e value when cal
10550 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
10560 65 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  e trigger contex
10570 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6d  t.**          im
10580 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65  mediately before
10590 20 61 6e 64 20 61 66 74 65 72 20 61 20 5b 52 4f   and after a [RO
105a0 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 41  LLBACK]..**.** A
105b0 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a  SSUMPTIONS:.**.*
105c0 2a 20 7b 41 31 32 32 33 32 7d 20 49 66 20 61 20  * {A12232} If a 
105d0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
105e0 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b  performs a new [
105f0 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73  INSERT] on the s
10600 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ame.**          
10610 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10620 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
10630 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
10640 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 20  rt_rowid()].**  
10650 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e          function
10660 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
10670 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
10680 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
10690 77 69 64 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  wid],.**        
106a0 20 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65    then the value
106b0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
106c0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
106d0 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
106e0 20 20 20 20 20 20 20 20 20 20 75 6e 70 72 65 64            unpred
106f0 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
10700 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
10710 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
10720 65 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20  e new.**        
10730 20 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72    last insert [r
10740 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65  owid]..*/.sqlite
10750 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
10760 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
10770 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
10780 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
10790 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
107a0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20  f Rows Modified 
107b0 7b 48 31 32 32 34 30 7d 20 3c 53 31 30 36 30 30  {H12240} <S10600
107c0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e  >.**.** This fun
107d0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
107e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61  e number of data
107f0 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77  base rows that w
10800 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f  ere changed.** o
10810 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  r inserted or de
10820 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
10830 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
10840 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  eted SQL stateme
10850 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61  nt.** on the [da
10860 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10870 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20  n] specified by 
10880 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
10890 74 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68 61  ter..** Only cha
108a0 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69  nges that are di
108b0 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64  rectly specified
108c0 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d   by the [INSERT]
108d0 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f  , [UPDATE],.** o
108e0 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
108f0 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64  ment are counted
10900 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61  .  Auxiliary cha
10910 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a  nges caused by.*
10920 2a 20 74 72 69 67 67 65 72 73 20 61 72 65 20 6e  * triggers are n
10930 6f 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65 20  ot counted. Use 
10940 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
10950 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75  al_changes()] fu
10960 6e 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e  nction.** to fin
10970 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  d the total numb
10980 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e  er of changes in
10990 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20  cluding changes 
109a0 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65  caused by trigge
109b0 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77  rs..**.** A "row
109c0 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68   change" is a ch
109d0 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65  ange to a single
109e0 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65   row of a single
109f0 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64   table.** caused
10a00 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44   by an INSERT, D
10a10 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45  ELETE, or UPDATE
10a20 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77   statement.  Row
10a30 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68  s that.** are ch
10a40 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66  anged as side ef
10a50 66 65 63 74 73 20 6f 66 20 52 45 50 4c 41 43 45  fects of REPLACE
10a60 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
10a70 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62  lution,.** rollb
10a80 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65  ack, ABORT proce
10a90 73 73 69 6e 67 2c 20 44 52 4f 50 20 54 41 42 4c  ssing, DROP TABL
10aa0 45 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68  E, or by any oth
10ab0 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73  er.** mechanisms
10ac0 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
10ad0 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
10ae0 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72  ges..**.** A "tr
10af0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69  igger context" i
10b00 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65  s a scope of exe
10b10 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69  cution that begi
10b20 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77  ns and.** ends w
10b30 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f  ith the script o
10b40 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 4d 6f  f a trigger.  Mo
10b50 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
10b60 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74  s are.** evaluat
10b70 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  ed outside of an
10b80 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73  y trigger.  This
10b90 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76   is the "top lev
10ba0 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  el".** trigger c
10bb0 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72  ontext.  If a tr
10bc0 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d  igger fires from
10bd0 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
10be0 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72  a.** new trigger
10bf0 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65   context is ente
10c00 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61  red for the dura
10c10 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65  tion of that one
10c20 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75  .** trigger.  Su
10c30 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65  btriggers create
10c40 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72   subcontexts for
10c50 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e   their duration.
10c60 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b  .**.** Calling [
10c70 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
10c80 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  or [sqlite3_step
10c90 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20  ()] recursively 
10ca0 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61  does.** not crea
10cb0 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72  te a new trigger
10cc0 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
10cd0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
10ce0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
10cf0 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63   of direct row c
10d00 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a  hanges in the.**
10d10 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
10d20 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
10d30 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
10d40 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
10d50 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
10d60 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73 2c  ext..**.** Thus,
10d70 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
10d80 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
10d90 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
10da0 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75  eturns the.** nu
10db0 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
10dc0 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
10dd0 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
10de0 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
10df0 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72  that also occurr
10e00 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65  ed at the top le
10e10 76 65 6c 2e 20 20 57 69 74 68 69 6e 20 74 68 65  vel.  Within the
10e20 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67   body of a trigg
10e30 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  er,.** the sqlit
10e40 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74  e3_changes() int
10e50 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61  erface can be ca
10e60 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  lled to find the
10e70 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
10e80 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
10e90 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
10ea0 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44  eted INSERT, UPD
10eb0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
10ec0 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  * statement with
10ed0 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74  in the body of t
10ee0 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
10ef0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
10f00 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64   number returned
10f10 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
10f20 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75  e changes.** cau
10f30 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65  sed by subtrigge
10f40 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68  rs since those h
10f50 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f  ave their own co
10f60 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ntext..**.** SQL
10f70 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  ite implements t
10f80 68 65 20 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45  he command "DELE
10f90 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22 20 77  TE FROM table" w
10fa0 69 74 68 6f 75 74 20 61 20 57 48 45 52 45 20 63  ithout a WHERE c
10fb0 6c 61 75 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70  lause.** by drop
10fc0 70 69 6e 67 20 61 6e 64 20 72 65 63 72 65 61 74  ping and recreat
10fd0 69 6e 67 20 74 68 65 20 74 61 62 6c 65 2e 20 20  ing the table.  
10fe0 44 6f 69 6e 67 20 73 6f 20 69 73 20 6d 75 63 68  Doing so is much
10ff0 20 66 61 73 74 65 72 20 74 68 61 6e 20 67 6f 69   faster than goi
11000 6e 67 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 6e  ng.** through an
11010 64 20 64 65 6c 65 74 69 6e 67 20 69 6e 64 69 76  d deleting indiv
11020 69 64 75 61 6c 20 65 6c 65 6d 65 6e 74 73 20 66  idual elements f
11030 72 6f 6d 20 74 68 65 20 74 61 62 6c 65 2e 20 20  rom the table.  
11040 42 65 63 61 75 73 65 20 6f 66 20 74 68 69 73 0a  Because of this.
11050 2a 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c  ** optimization,
11060 20 74 68 65 20 64 65 6c 65 74 69 6f 6e 73 20 69   the deletions i
11070 6e 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  n "DELETE FROM t
11080 61 62 6c 65 22 20 61 72 65 20 6e 6f 74 20 72 6f  able" are not ro
11090 77 20 63 68 61 6e 67 65 73 20 61 6e 64 0a 2a 2a  w changes and.**
110a0 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 63 6f 75   will not be cou
110b0 6e 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  nted by the sqli
110c0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 6f 72  te3_changes() or
110d0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
110e0 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a 20 66 75  changes()].** fu
110f0 6e 63 74 69 6f 6e 73 2c 20 72 65 67 61 72 64 6c  nctions, regardl
11100 65 73 73 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ess of the numbe
11110 72 20 6f 66 20 65 6c 65 6d 65 6e 74 73 20 74 68  r of elements th
11120 61 74 20 77 65 72 65 20 6f 72 69 67 69 6e 61 6c  at were original
11130 6c 79 0a 2a 2a 20 69 6e 20 74 68 65 20 74 61 62  ly.** in the tab
11140 6c 65 2e 20 20 54 6f 20 67 65 74 20 61 6e 20 61  le.  To get an a
11150 63 63 75 72 61 74 65 20 63 6f 75 6e 74 20 6f 66  ccurate count of
11160 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
11170 6f 77 73 20 64 65 6c 65 74 65 64 2c 20 75 73 65  ows deleted, use
11180 0a 2a 2a 20 22 44 45 4c 45 54 45 20 46 52 4f 4d  .** "DELETE FROM
11190 20 74 61 62 6c 65 20 57 48 45 52 45 20 31 22 20   table WHERE 1" 
111a0 69 6e 73 74 65 61 64 2e 20 20 4f 72 20 72 65 63  instead.  Or rec
111b0 6f 6d 70 69 6c 65 20 75 73 69 6e 67 20 74 68 65  ompile using the
111c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  .** [SQLITE_OMIT
111d0 5f 54 52 55 4e 43 41 54 45 5f 4f 50 54 49 4d 49  _TRUNCATE_OPTIMI
111e0 5a 41 54 49 4f 4e 5d 20 63 6f 6d 70 69 6c 65 2d  ZATION] compile-
111f0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 6f 20 64  time option to d
11200 69 73 61 62 6c 65 20 74 68 65 0a 2a 2a 20 6f 70  isable the.** op
11210 74 69 6d 69 7a 61 74 69 6f 6e 20 6f 6e 20 61 6c  timization on al
11220 6c 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  l queries..**.**
11230 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
11240 2a 2a 20 7b 48 31 32 32 34 31 7d 20 54 68 65 20  ** {H12241} The 
11250 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
11260 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 73 68 61  ()] function sha
11270 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 6e 75  ll return the nu
11280 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20 20 20 20  mber of.**      
11290 20 20 20 20 72 6f 77 20 63 68 61 6e 67 65 73 20      row changes 
112a0 63 61 75 73 65 64 20 62 79 20 74 68 65 20 6d 6f  caused by the mo
112b0 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
112c0 2c 20 55 50 44 41 54 45 2c 0a 2a 2a 20 20 20 20  , UPDATE,.**    
112d0 20 20 20 20 20 20 6f 72 20 44 45 4c 45 54 45 20        or DELETE 
112e0 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65  statement on the
112f0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
11300 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 0a 2a 2a  onnection and.**
11310 20 20 20 20 20 20 20 20 20 20 77 69 74 68 69 6e            within
11320 20 74 68 65 20 73 61 6d 65 20 6f 72 20 68 69 67   the same or hig
11330 68 65 72 20 74 72 69 67 67 65 72 20 63 6f 6e 74  her trigger cont
11340 65 78 74 2c 20 6f 72 20 7a 65 72 6f 20 69 66 20  ext, or zero if 
11350 74 68 65 72 65 20 68 61 76 65 0a 2a 2a 20 20 20  there have.**   
11360 20 20 20 20 20 20 20 6e 6f 74 20 62 65 65 6e 20         not been 
11370 61 6e 79 20 71 75 61 6c 69 66 79 69 6e 67 20 72  any qualifying r
11380 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a  ow changes..**.*
11390 2a 20 7b 48 31 32 32 34 33 7d 20 53 74 61 74 65  * {H12243} State
113a0 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72  ments of the for
113b0 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  m "DELETE FROM t
113c0 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68 20 6e  ablename" with n
113d0 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 57 48  o.**          WH
113e0 45 52 45 20 63 6c 61 75 73 65 20 73 68 61 6c 6c  ERE clause shall
113f0 20 63 61 75 73 65 20 73 75 62 73 65 71 75 65 6e   cause subsequen
11400 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 20 20  t calls to.**   
11410 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
11420 63 68 61 6e 67 65 73 28 29 5d 20 74 6f 20 72 65  changes()] to re
11430 74 75 72 6e 20 7a 65 72 6f 2c 20 72 65 67 61 72  turn zero, regar
11440 64 6c 65 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  dless of the.** 
11450 20 20 20 20 20 20 20 20 20 6e 75 6d 62 65 72 20           number 
11460 6f 66 20 72 6f 77 73 20 6f 72 69 67 69 6e 61 6c  of rows original
11470 6c 79 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e  ly in the table.
11480 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f  .**.** ASSUMPTIO
11490 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 32 32 35  NS:.**.** {A1225
114a0 32 7d 20 49 66 20 61 20 73 65 70 61 72 61 74 65  2} If a separate
114b0 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
114c0 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
114d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
114e0 63 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20  ction.**        
114f0 20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33    while [sqlite3
11500 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
11510 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
11520 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
11530 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 75 6e  *          is un
11540 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
11550 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
11560 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
11570 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
11580 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11590 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
115a0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
115b0 20 7b 48 31 32 32 36 30 7d 20 3c 53 31 30 36 30   {H12260} <S1060
115c0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  0>.**.** This fu
115d0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
115e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
115f0 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
11600 62 79 20 49 4e 53 45 52 54 2c 0a 2a 2a 20 55 50  by INSERT,.** UP
11610 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
11620 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20  tatements since 
11630 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
11640 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70  nnection] was op
11650 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 63 6f 75  ened..** The cou
11660 6e 74 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  nt includes all 
11670 63 68 61 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c  changes from all
11680 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
11690 73 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  s.  However,.** 
116a0 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  the count does n
116b0 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
116c0 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  es used to imple
116d0 6d 65 6e 74 20 52 45 50 4c 41 43 45 20 63 6f 6e  ment REPLACE con
116e0 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20  straints,.** do 
116f0 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f  rollbacks or ABO
11700 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f  RT processing, o
11710 72 20 44 52 4f 50 20 74 61 62 6c 65 20 70 72 6f  r DROP table pro
11720 63 65 73 73 69 6e 67 2e 0a 2a 2a 20 54 68 65 20  cessing..** The 
11730 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e  changes are coun
11740 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
11750 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
11760 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 0a  t makes them is.
11770 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68  ** completed (wh
11780 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  en the statement
11790 20 68 61 6e 64 6c 65 20 69 73 20 70 61 73 73 65   handle is passe
117a0 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
117b0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
117c0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
117d0 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ])..**.** SQLite
117e0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
117f0 63 6f 6d 6d 61 6e 64 20 22 44 45 4c 45 54 45 20  command "DELETE 
11800 46 52 4f 4d 20 74 61 62 6c 65 22 20 77 69 74 68  FROM table" with
11810 6f 75 74 20 61 20 57 48 45 52 45 20 63 6c 61 75  out a WHERE clau
11820 73 65 0a 2a 2a 20 62 79 20 64 72 6f 70 70 69 6e  se.** by droppin
11830 67 20 61 6e 64 20 72 65 63 72 65 61 74 69 6e 67  g and recreating
11840 20 74 68 65 20 74 61 62 6c 65 2e 20 20 28 54 68   the table.  (Th
11850 69 73 20 69 73 20 6d 75 63 68 20 66 61 73 74 65  is is much faste
11860 72 20 74 68 61 6e 20 67 6f 69 6e 67 0a 2a 2a 20  r than going.** 
11870 74 68 72 6f 75 67 68 20 61 6e 64 20 64 65 6c 65  through and dele
11880 74 69 6e 67 20 69 6e 64 69 76 69 64 75 61 6c 20  ting individual 
11890 65 6c 65 6d 65 6e 74 73 20 66 72 6f 6d 20 74 68  elements from th
118a0 65 20 74 61 62 6c 65 2e 29 20 20 42 65 63 61 75  e table.)  Becau
118b0 73 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 6f 70  se of this.** op
118c0 74 69 6d 69 7a 61 74 69 6f 6e 2c 20 74 68 65 20  timization, the 
118d0 64 65 6c 65 74 69 6f 6e 73 20 69 6e 20 22 44 45  deletions in "DE
118e0 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c 65 22  LETE FROM table"
118f0 20 61 72 65 20 6e 6f 74 20 72 6f 77 20 63 68 61   are not row cha
11900 6e 67 65 73 20 61 6e 64 0a 2a 2a 20 77 69 6c 6c  nges and.** will
11910 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20   not be counted 
11920 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  by the sqlite3_c
11930 68 61 6e 67 65 73 28 29 20 6f 72 20 5b 73 71 6c  hanges() or [sql
11940 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
11950 65 73 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  es()].** functio
11960 6e 73 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ns, regardless o
11970 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  f the number of 
11980 65 6c 65 6d 65 6e 74 73 20 74 68 61 74 20 77 65  elements that we
11990 72 65 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  re originally.**
119a0 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2e 20 20   in the table.  
119b0 54 6f 20 67 65 74 20 61 6e 20 61 63 63 75 72 61  To get an accura
119c0 74 65 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20  te count of the 
119d0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 64  number of rows d
119e0 65 6c 65 74 65 64 2c 20 75 73 65 0a 2a 2a 20 22  eleted, use.** "
119f0 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 61 62 6c  DELETE FROM tabl
11a00 65 20 57 48 45 52 45 20 31 22 20 69 6e 73 74 65  e WHERE 1" inste
11a10 61 64 2e 20 20 20 4f 72 20 72 65 63 6f 6d 70 69  ad.   Or recompi
11a20 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
11a30 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 55  [SQLITE_OMIT_TRU
11a40 4e 43 41 54 45 5f 4f 50 54 49 4d 49 5a 41 54 49  NCATE_OPTIMIZATI
11a50 4f 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ON] compile-time
11a60 20 6f 70 74 69 6f 6e 20 74 6f 20 64 69 73 61 62   option to disab
11a70 6c 65 20 74 68 65 0a 2a 2a 20 6f 70 74 69 6d 69  le the.** optimi
11a80 7a 61 74 69 6f 6e 20 6f 6e 20 61 6c 6c 20 71 75  zation on all qu
11a90 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  eries..**.** See
11aa0 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
11ab0 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
11ac0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
11ad0 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a  NVARIANTS:.**.**
11ae0 20 7b 48 31 32 32 36 31 7d 20 54 68 65 20 5b 73   {H12261} The [s
11af0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
11b00 6e 67 65 73 28 29 5d 20 72 65 74 75 72 6e 73 20  nges()] returns 
11b10 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
11b20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20  .**          of 
11b30 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
11b40 65 64 20 62 79 20 49 4e 53 45 52 54 2c 20 55 50  ed by INSERT, UP
11b50 44 41 54 45 2c 20 61 6e 64 2f 6f 72 20 44 45 4c  DATE, and/or DEL
11b60 45 54 45 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ETE.**          
11b70 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 74 68  statements on th
11b80 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
11b90 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 69 6e   connection], in
11ba0 20 61 6e 79 0a 2a 2a 20 20 20 20 20 20 20 20 20   any.**         
11bb0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
11bc0 2c 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61  , since the data
11bd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
11be0 77 61 73 20 63 72 65 61 74 65 64 2e 0a 2a 2a 0a  was created..**.
11bf0 2a 2a 20 7b 48 31 32 32 36 33 7d 20 53 74 61 74  ** {H12263} Stat
11c00 65 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 66 6f  ements of the fo
11c10 72 6d 20 22 44 45 4c 45 54 45 20 46 52 4f 4d 20  rm "DELETE FROM 
11c20 74 61 62 6c 65 6e 61 6d 65 22 20 77 69 74 68 20  tablename" with 
11c30 6e 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 57  no.**          W
11c40 48 45 52 45 20 63 6c 61 75 73 65 20 73 68 61 6c  HERE clause shal
11c50 6c 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  l not change the
11c60 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
11c70 2a 2a 20 20 20 20 20 20 20 20 20 20 62 79 20 5b  **          by [
11c80 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
11c90 61 6e 67 65 73 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  anges()]..**.** 
11ca0 41 53 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a  ASSUMPTIONS:.**.
11cb0 2a 2a 20 7b 41 31 32 32 36 34 7d 20 49 66 20 61  ** {A12264} If a
11cc0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
11cd0 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
11ce0 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
11cf0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
11d00 2a 20 20 20 20 20 20 20 20 20 20 77 68 69 6c 65  *          while
11d10 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
11d20 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
11d30 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
11d40 61 6c 75 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  alue.**         
11d50 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
11d60 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
11d70 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
11d80 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  /.int sqlite3_to
11d90 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
11da0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
11db0 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
11dc0 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
11dd0 20 51 75 65 72 79 20 7b 48 31 32 32 37 30 7d 20   Query {H12270} 
11de0 3c 53 33 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S30500>.**.** T
11df0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
11e00 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
11e10 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
11e20 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
11e30 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
11e40 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
11e50 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
11e60 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
11e70 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
11e80 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
11e90 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
11ea0 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
11eb0 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
11ec0 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
11ed0 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
11ee0 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
11ef0 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
11f00 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 73  y..**.** It is s
11f10 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
11f20 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
11f30 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
11f40 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
11f50 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
11f60 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
11f70 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
11f80 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
11f90 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
11fa0 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
11fb0 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
11fc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
11fd0 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
11fe0 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
11ff0 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
12000 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
12010 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ns..**.** If an 
12020 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
12030 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e   very nearly fin
12040 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d  ished at the tim
12050 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  e when.** sqlite
12060 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73  3_interrupt() is
12070 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74   called, then it
12080 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20   might not have 
12090 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a  an opportunity.*
120a0 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70  * to be interrup
120b0 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f  ted and might co
120c0 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65  ntinue to comple
120d0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 53  tion..**.** An S
120e0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
120f0 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
12100 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
12110 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
12120 0a 2a 2a 20 49 66 20 74 68 65 20 69 6e 74 65 72  .** If the inter
12130 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
12140 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
12150 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
12160 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
12170 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
12180 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
12190 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
121a0 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
121b0 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
121c0 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
121d0 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
121e0 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
121f0 75 70 74 28 29 20 68 61 73 20 6e 6f 20 65 66 66  upt() has no eff
12200 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
12210 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
12220 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
12230 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
12240 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
12250 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
12260 2a 0a 2a 2a 20 7b 48 31 32 32 37 31 7d 20 54 68  *.** {H12271} Th
12270 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
12280 72 75 70 74 28 29 5d 20 69 6e 74 65 72 66 61 63  rupt()] interfac
12290 65 20 77 69 6c 6c 20 66 6f 72 63 65 20 61 6c 6c  e will force all
122a0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 20 20 20 20   running.**     
122b0 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65       SQL stateme
122c0 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
122d0 69 74 68 20 74 68 65 20 73 61 6d 65 20 64 61 74  ith the same dat
122e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
122f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f 20  .**          to 
12300 68 61 6c 74 20 61 66 74 65 72 20 70 72 6f 63 65  halt after proce
12310 73 73 69 6e 67 20 61 74 20 6d 6f 73 74 20 6f 6e  ssing at most on
12320 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 6f 77  e additional row
12330 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
12340 7b 48 31 32 32 37 32 7d 20 41 6e 79 20 53 51 4c  {H12272} Any SQL
12350 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
12360 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 62  is interrupted b
12370 79 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  y [sqlite3_inter
12380 72 75 70 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20  rupt()].**      
12390 20 20 20 20 77 69 6c 6c 20 72 65 74 75 72 6e 20      will return 
123a0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
123b0 54 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50  T]..**.** ASSUMP
123c0 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31  TIONS:.**.** {A1
123d0 32 32 37 39 7d 20 49 66 20 74 68 65 20 64 61 74  2279} If the dat
123e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
123f0 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73   closes while [s
12400 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
12410 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ()].**          
12420 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
12430 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
12440 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
12450 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  /.void sqlite3_i
12460 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
12470 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
12480 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
12490 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
124a0 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 20 7b  nt Is Complete {
124b0 48 31 30 35 31 30 7d 20 3c 53 37 30 32 30 30 3e  H10510} <S70200>
124c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
124d0 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
124e0 20 66 6f 72 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e   for command-lin
124f0 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
12500 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
12510 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
12520 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
12530 6f 72 6d 20 63 6f 6d 70 6c 65 74 65 20 61 20 53  orm complete a S
12540 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
12550 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
12560 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
12570 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
12580 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
12590 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
125a0 69 6e 67 2e 20 20 54 68 65 73 65 20 72 6f 75 74  ing.  These rout
125b0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 72 75 65  ines return true
125c0 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74   if the input st
125d0 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20  ring.** appears 
125e0 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65  to be a complete
125f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
12600 20 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20   A statement is 
12610 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
12620 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
12630 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
12640 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
12650 73 20 6e 6f 74 20 61 20 66 72 61 67 6d 65 6e 74  s not a fragment
12660 20 6f 66 20 61 0a 2a 2a 20 43 52 45 41 54 45 20   of a.** CREATE 
12670 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e  TRIGGER statemen
12680 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  t.  Semicolons t
12690 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
126a0 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
126b0 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
126c0 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
126d0 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
126e0 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
126f0 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
12700 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
12710 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
12720 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
12730 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
12740 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
12750 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
12760 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
12770 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
12780 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68   do not parse th
12790 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
127a0 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f   thus.** will no
127b0 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
127c0 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
127d0 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41   SQL..**.** INVA
127e0 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
127f0 31 30 35 31 31 7d 20 41 20 73 75 63 63 65 73 73  10511} A success
12800 66 75 6c 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ful evaluation o
12810 66 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  f [sqlite3_compl
12820 65 74 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  ete()] or.**    
12830 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
12840 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 66 75 6e  omplete16()] fun
12850 63 74 69 6f 6e 73 20 73 68 61 6c 6c 0a 2a 2a 20  ctions shall.** 
12860 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
12870 61 20 6e 75 6d 65 72 69 63 20 31 20 69 66 20 61  a numeric 1 if a
12880 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 6c  nd only if the l
12890 61 73 74 20 6e 6f 6e 2d 77 68 69 74 65 73 70 61  ast non-whitespa
128a0 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ce.**          t
128b0 6f 6b 65 6e 20 69 6e 20 74 68 65 69 72 20 69 6e  oken in their in
128c0 70 75 74 20 69 73 20 61 20 73 65 6d 69 63 6f 6c  put is a semicol
128d0 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 69  on that is not i
128e0 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 20 20 20  n between.**    
128f0 20 20 20 20 20 20 74 68 65 20 42 45 47 49 4e 20        the BEGIN 
12900 61 6e 64 20 45 4e 44 20 6f 66 20 61 20 43 52 45  and END of a CRE
12910 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
12920 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ement..**.** {H1
12930 30 35 31 32 7d 20 49 66 20 61 20 6d 65 6d 6f 72  0512} If a memor
12940 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
12950 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
12960 20 61 6e 20 69 6e 76 6f 63 61 74 69 6f 6e 0a 2a   an invocation.*
12970 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 5b 73  *          of [s
12980 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
12990 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63  )] or [sqlite3_c
129a0 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 74 68 65  omplete16()] the
129b0 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
129c0 20 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c 20    routine shall 
129d0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
129e0 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 41 53 53  OMEM]..**.** ASS
129f0 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20  UMPTIONS:.**.** 
12a00 7b 41 31 30 35 31 32 7d 20 54 68 65 20 69 6e 70  {A10512} The inp
12a10 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
12a20 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
12a30 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
12a40 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  ated.**         
12a50 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
12a60 2a 0a 2a 2a 20 7b 41 31 30 35 31 33 7d 20 54 68  *.** {A10513} Th
12a70 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
12a80 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
12a90 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
12aa0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20  -terminated.**  
12ab0 20 20 20 20 20 20 20 20 55 54 46 2d 31 36 20 73          UTF-16 s
12ac0 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
12ad0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
12ae0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
12af0 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
12b00 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
12b10 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
12b20 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
12b30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12b40 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
12b50 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
12b60 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
12b70 20 7b 48 31 32 33 31 30 7d 20 3c 53 34 30 34 30   {H12310} <S4040
12b80 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
12b90 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
12ba0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74  lback function t
12bb0 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
12bc0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a  oked whenever.**
12bd0 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
12be0 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61  ade to open a da
12bf0 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61  tabase table tha
12c00 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  t another thread
12c10 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
12c20 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a  as locked..**.**
12c30 20 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c   If the busy cal
12c40 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
12c50 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
12c60 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
12c70 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
12c80 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
12c90 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
12ca0 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
12cb0 6b 2e 20 49 66 20 74 68 65 20 62 75 73 79 20 63  k. If the busy c
12cc0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
12cd0 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
12ce0 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 20 62   callback will b
12cf0 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
12d00 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
12d10 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
12d20 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 68 61  gument to the ha
12d30 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
12d40 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
12d50 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
12d60 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
12d70 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
12d80 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
12d90 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
12da0 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 68 61  ent to.** the ha
12db0 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
12dc0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
12dd0 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
12de0 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
12df0 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
12e00 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67  for this locking
12e10 20 65 76 65 6e 74 2e 20 20 49 66 20 74 68 65 0a   event.  If the.
12e20 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
12e30 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
12e40 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
12e50 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
12e60 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
12e70 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
12e80 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
12e90 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
12ea0 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e  OCKED] is return
12eb0 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61  ed..** If the ca
12ec0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
12ed0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
12ee0 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
12ef0 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
12f00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
12f10 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
12f20 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
12f30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
12f40 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
12f50 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
12f60 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
12f70 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
12f80 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
12f90 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
12fa0 6e 2e 20 49 66 20 53 51 4c 69 74 65 20 64 65 74  n. If SQLite det
12fb0 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
12fc0 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
12fd0 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
12fe0 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
12ff0 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
13000 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
13010 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
13020 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
13030 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73  ERR_BLOCKED] ins
13040 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
13050 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
13060 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
13070 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
13080 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
13090 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
130a0 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
130b0 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
130c0 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
130d0 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
130e0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
130f0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
13100 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
13110 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
13120 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
13130 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
13140 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
13150 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
13160 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
13170 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
13180 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
13190 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
131a0 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
131b0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
131c0 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
131d0 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
131e0 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
131f0 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
13200 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
13210 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
13220 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
13230 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
13240 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
13250 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
13260 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
13270 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
13280 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
13290 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
132a0 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
132b0 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
132c0 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
132d0 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
132e0 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  *.** The default
132f0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
13300 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  s NULL..**.** Th
13310 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  e [SQLITE_BUSY] 
13320 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74  error is convert
13330 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f  ed to [SQLITE_IO
13340 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
13350 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69  when SQLite is i
13360 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20  n the middle of 
13370 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74  a large transact
13380 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68  ion where all th
13390 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c  e.** changes wil
133a0 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74  l not fit into t
133b0 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63  he in-memory cac
133c0 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  he.  SQLite will
133d0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64  .** already hold
133e0 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b   a RESERVED lock
133f0 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
13400 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65   file, but it ne
13410 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  eds.** to promot
13420 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45  e this lock to E
13430 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74  XCLUSIVE so that
13440 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61   it can spill ca
13450 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74  che.** pages int
13460 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
13470 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d  ile without harm
13480 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a   to concurrent.*
13490 2a 20 72 65 61 64 65 72 73 2e 20 20 49 66 20 69  * readers.  If i
134a0 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70  t is unable to p
134b0 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c  romote the lock,
134c0 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d   then the in-mem
134d0 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c  ory.** cache wil
134e0 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20  l be left in an 
134f0 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61  inconsistent sta
13500 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72  te and so the er
13510 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70  ror.** code is p
13520 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65  romoted from the
13530 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69   relatively beni
13540 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  gn [SQLITE_BUSY]
13550 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20   to.** the more 
13560 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49  severe [SQLITE_I
13570 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20  OERR_BLOCKED].  
13580 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20  This error code 
13590 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72  promotion.** for
135a0 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63  ces an automatic
135b0 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   rollback of the
135c0 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74   changes.  See t
135d0 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f  he.** <a href="/
135e0 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43  cvstrac/wiki?p=C
135f0 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
13600 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a  ngBusyError">.**
13610 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f   CorruptionFollo
13620 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61  wingBusyError</a
13630 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20  > wiki page for 
13640 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20  a discussion of 
13650 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69  why.** this is i
13660 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20  mportant..**.** 
13670 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
13680 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
13690 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
136a0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
136b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
136c0 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
136d0 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
136e0 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
136f0 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
13700 6c 65 72 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  ler.  Note that 
13710 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
13720 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
13730 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
13740 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
13750 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
13760 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
13770 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
13780 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
13790 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
137a0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
137b0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
137c0 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
137d0 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63  andler.  Any suc
137e0 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
137f0 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
13800 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
13810 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
13820 0a 2a 2a 20 7b 48 31 32 33 31 31 7d 20 54 68 65  .** {H12311} The
13830 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
13840 61 6e 64 6c 65 72 28 44 2c 43 2c 41 29 5d 20 66  andler(D,C,A)] f
13850 75 6e 63 74 69 6f 6e 20 73 68 61 6c 6c 20 72 65  unction shall re
13860 70 6c 61 63 65 0a 2a 2a 20 20 20 20 20 20 20 20  place.**        
13870 20 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20    busy callback 
13880 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  in the [database
13890 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77   connection] D w
138a0 69 74 68 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20  ith a new.**    
138b0 20 20 20 20 20 20 61 20 6e 65 77 20 62 75 73 79        a new busy
138c0 20 68 61 6e 64 6c 65 72 20 43 20 61 6e 64 20 61   handler C and a
138d0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
138e0 70 6f 69 6e 74 65 72 20 41 2e 0a 2a 2a 0a 2a 2a  pointer A..**.**
138f0 20 7b 48 31 32 33 31 32 7d 20 4e 65 77 6c 79 20   {H12312} Newly 
13900 63 72 65 61 74 65 64 20 5b 64 61 74 61 62 61 73  created [databas
13910 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 73  e connections] s
13920 68 61 6c 6c 20 68 61 76 65 20 61 20 62 75 73 79  hall have a busy
13930 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 68 61 6e  .**          han
13940 64 6c 65 72 20 6f 66 20 4e 55 4c 4c 2e 0a 2a 2a  dler of NULL..**
13950 0a 2a 2a 20 7b 48 31 32 33 31 34 7d 20 57 68 65  .** {H12314} Whe
13960 6e 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 5b 64  n two or more [d
13970 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13980 6f 6e 73 5d 20 73 68 61 72 65 20 61 0a 2a 2a 20  ons] share a.** 
13990 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
139a0 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
139b0 63 61 63 68 65 20 7c 20 63 6f 6d 6d 6f 6e 20 63  cache | common c
139c0 61 63 68 65 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  ache],.**       
139d0 20 20 20 74 68 65 20 62 75 73 79 20 68 61 6e 64     the busy hand
139e0 6c 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61  ler for the data
139f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
13a00 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 0a  currently using.
13a10 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
13a20 63 61 63 68 65 20 73 68 61 6c 6c 20 62 65 20 69  cache shall be i
13a30 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
13a40 63 61 63 68 65 20 65 6e 63 6f 75 6e 74 65 72 73  cache encounters
13a50 20 61 20 6c 6f 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b   a lock..**.** {
13a60 48 31 32 33 31 36 7d 20 49 66 20 61 20 62 75 73  H12316} If a bus
13a70 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
13a80 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  ck returns zero,
13a90 20 74 68 65 6e 20 74 68 65 20 53 51 4c 69 74 65   then the SQLite
13aa0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20   interface.**   
13ab0 20 20 20 20 20 20 20 74 68 61 74 20 70 72 6f 76         that prov
13ac0 6f 6b 65 64 20 74 68 65 20 6c 6f 63 6b 69 6e 67  oked the locking
13ad0 20 65 76 65 6e 74 20 73 68 61 6c 6c 20 72 65 74   event shall ret
13ae0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
13af0 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 31 38  ]..**.** {H12318
13b00 7d 20 53 51 4c 69 74 65 20 73 68 61 6c 6c 20 69  } SQLite shall i
13b10 6e 76 6f 6b 65 73 20 74 68 65 20 62 75 73 79 20  nvokes the busy 
13b20 68 61 6e 64 6c 65 72 20 77 69 74 68 20 74 77 6f  handler with two
13b30 20 61 72 67 75 6d 65 6e 74 73 20 77 68 69 63 68   arguments which
13b40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 65  .**          are
13b50 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70   a copy of the p
13b60 6f 69 6e 74 65 72 20 73 75 70 70 6c 69 65 64 20  ointer supplied 
13b70 62 79 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  by the 3rd param
13b80 65 74 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  eter to.**      
13b90 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 75 73      [sqlite3_bus
13ba0 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 61 6e 64  y_handler()] and
13bb0 20 61 20 63 6f 75 6e 74 20 6f 66 20 74 68 65 20   a count of the 
13bc0 6e 75 6d 62 65 72 20 6f 66 20 70 72 69 6f 72 0a  number of prior.
13bd0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 76 6f  **          invo
13be0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  cations of the b
13bf0 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
13c00 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67  the same locking
13c10 20 65 76 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 41 53   event..**.** AS
13c20 53 55 4d 50 54 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a  SUMPTIONS:.**.**
13c30 20 7b 41 31 32 33 31 39 7d 20 41 20 62 75 73 79   {A12319} A busy
13c40 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
13c50 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
13c60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
13c70 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b  **          or [
13c80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
13c90 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
13ca0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
13cb0 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
13cc0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
13cd0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
13ce0 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
13cf0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
13d00 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
13d10 54 69 6d 65 6f 75 74 20 7b 48 31 32 33 34 30 7d  Timeout {H12340}
13d20 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S40410>.**.** 
13d30 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
13d40 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
13d50 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
13d60 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
13d70 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
13d80 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
13d90 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
13da0 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
13db0 20 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20   The handler.** 
13dc0 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
13dd0 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
13de0 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
13df0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
13e00 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
13e10 63 63 75 6d 75 6c 61 74 65 64 2e 20 7b 48 31 32  ccumulated. {H12
13e20 33 34 33 7d 20 41 66 74 65 72 20 22 6d 73 22 20  343} After "ms" 
13e30 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
13e40 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
13e50 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
13e60 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
13e70 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
13e80 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
13e90 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
13ea0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
13eb0 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c  CKED]..**.** Cal
13ec0 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
13ed0 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65  e with an argume
13ee0 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  nt less than or 
13ef0 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a  equal to zero.**
13f00 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62   turns off all b
13f10 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a  usy handlers..**
13f20 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e  .** There can on
13f30 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
13f40 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
13f50 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
13f60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
13f70 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69  tion] any any gi
13f80 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
13f90 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
13fa0 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
13fb0 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
13fc0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
13fd0 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
13fe0 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
13ff0 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
14000 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
14010 69 73 20 63 6c 65 61 72 65 64 2e 0a 2a 2a 0a 2a  is cleared..**.*
14020 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
14030 0a 2a 2a 20 7b 48 31 32 33 34 31 7d 20 54 68 65  .** {H12341} The
14040 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
14050 69 6d 65 6f 75 74 28 29 5d 20 66 75 6e 63 74 69  imeout()] functi
14060 6f 6e 20 73 68 61 6c 6c 20 6f 76 65 72 72 69 64  on shall overrid
14070 65 20 61 6e 79 20 70 72 69 6f 72 0a 2a 2a 20 20  e any prior.**  
14080 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
14090 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
140a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62 75 73   or [sqlite3_bus
140b0 79 5f 68 61 6e 64 6c 65 72 28 29 5d 20 73 65 74  y_handler()] set
140c0 74 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ting.**         
140d0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
140e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
140f0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 34  n]..**.** {H1234
14100 33 7d 20 49 66 20 74 68 65 20 32 6e 64 20 70 61  3} If the 2nd pa
14110 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
14120 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
14130 28 29 5d 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ()] is less than
14140 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
14150 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 2c 20 74  equal to zero, t
14160 68 65 6e 20 74 68 65 20 62 75 73 79 20 68 61 6e  hen the busy han
14170 64 6c 65 72 20 73 68 61 6c 6c 20 62 65 20 63 6c  dler shall be cl
14180 65 61 72 65 64 20 73 6f 20 74 68 61 74 0a 2a 2a  eared so that.**
14190 20 20 20 20 20 20 20 20 20 20 61 6c 6c 20 73 75            all su
141a0 62 73 65 71 75 65 6e 74 20 6c 6f 63 6b 69 6e 67  bsequent locking
141b0 20 65 76 65 6e 74 73 20 69 6d 6d 65 64 69 61 74   events immediat
141c0 65 6c 79 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ely return [SQLI
141d0 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_BUSY]..**.** 
141e0 7b 48 31 32 33 34 34 7d 20 49 66 20 74 68 65 20  {H12344} If the 
141f0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
14200 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
14210 69 6d 65 6f 75 74 28 29 5d 20 69 73 20 61 20 70  imeout()] is a p
14220 6f 73 69 74 69 76 65 0a 2a 2a 20 20 20 20 20 20  ositive.**      
14230 20 20 20 20 6e 75 6d 62 65 72 20 4e 2c 20 74 68      number N, th
14240 65 6e 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  en a busy handle
14250 72 20 73 68 61 6c 6c 20 62 65 20 73 65 74 20 74  r shall be set t
14260 68 61 74 20 72 65 70 65 61 74 65 64 6c 79 20 63  hat repeatedly c
14270 61 6c 6c 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  alls.**         
14280 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65   the xSleep() me
14290 74 68 6f 64 20 69 6e 20 74 68 65 20 5b 73 71 6c  thod in the [sql
142a0 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 20 69  ite3_vfs | VFS i
142b0 6e 74 65 72 66 61 63 65 5d 20 75 6e 74 69 6c 0a  nterface] until.
142c0 2a 2a 20 20 20 20 20 20 20 20 20 20 65 69 74 68  **          eith
142d0 65 72 20 74 68 65 20 6c 6f 63 6b 20 63 6c 65 61  er the lock clea
142e0 72 73 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  rs or until the 
142f0 63 75 6d 75 6c 61 74 69 76 65 20 73 6c 65 65 70  cumulative sleep
14300 20 74 69 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20   time.**        
14310 20 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20    reported back 
14320 62 79 20 78 53 6c 65 65 70 28 29 20 65 78 63 65  by xSleep() exce
14330 65 64 73 20 4e 20 6d 69 6c 6c 69 73 65 63 6f 6e  eds N millisecon
14340 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ds..*/.int sqlit
14350 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
14360 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73  sqlite3*, int ms
14370 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
14380 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20  EF: Convenience 
14390 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e  Routines For Run
143a0 6e 69 6e 67 20 51 75 65 72 69 65 73 20 7b 48 31  ning Queries {H1
143b0 32 33 37 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a  2370} <S10000>.*
143c0 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a  *.** Definition:
143d0 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62   A <b>result tab
143e0 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79  le</b> is memory
143f0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20   data structure 
14400 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a  created by the.*
14410 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
14420 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63  able()] interfac
14430 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62  e.  A result tab
14440 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a  le records the.*
14450 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79  * complete query
14460 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e   results from on
14470 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65  e or more querie
14480 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  s..**.** The tab
14490 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20  le conceptually 
144a0 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  has a number of 
144b0 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73  rows and columns
144c0 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20  .  But.** these 
144d0 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20  numbers are not 
144e0 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75  part of the resu
144f0 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e  lt table itself.
14500 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65    These.** numbe
14510 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20  rs are obtained 
14520 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74  separately.  Let
14530 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   N be the number
14540 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20   of rows.** and 
14550 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  M be the number 
14560 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a  of columns..**.*
14570 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
14580 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
14590 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f  pointers to zero
145a0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
145b0 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  8 strings..** Th
145c0 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20  ere are (N+1)*M 
145d0 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  elements in the 
145e0 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73  array.  The firs
145f0 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69  t M pointers poi
14600 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65  nt.** to zero-te
14610 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
14620 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74   that  contain t
14630 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20  he names of the 
14640 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20  columns..** The 
14650 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65  remaining entrie
14660 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71  s all point to q
14670 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e  uery results.  N
14680 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c  ULL values resul
14690 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69  t.** in NULL poi
146a0 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65  nters.  All othe
146b0 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20  r values are in 
146c0 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f  their UTF-8 zero
146d0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
146e0 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61  tring representa
146f0 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64  tion as returned
14700 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
14710 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
14720 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
14730 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20  e might consist 
14740 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d  of one or more m
14750 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14760 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  s..** It is not 
14770 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72  safe to pass a r
14780 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65  esult table dire
14790 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33  ctly to [sqlite3
147a0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72  _free()]..** A r
147b0 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75  esult table shou
147c0 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ld be deallocate
147d0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
147e0 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a  _free_table()]..
147f0 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61 6d  **.** As an exam
14800 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
14810 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
14820 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
14830 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
14840 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
14850 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
14860 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
14870 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
14880 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
14890 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
148a0 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
148b0 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
148c0 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
148d0 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
148e0 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
148f0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
14900 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
14910 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
14920 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
14930 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
14940 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
14950 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
14960 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
14970 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
14980 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
14990 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
149a0 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
149b0 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
149c0 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
149d0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
149e0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
149f0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
14a00 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
14a10 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
14a20 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
14a30 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
14a40 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
14a50 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
14a60 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
14a70 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
14a80 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
14a90 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
14aa0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
14ab0 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
14ac0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
14ad0 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
14ae0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
14af0 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
14b00 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
14b10 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
14b20 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
14b30 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65  ble() function e
14b40 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20  valuates one or 
14b50 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  more.** semicolo
14b60 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20  n-separated SQL 
14b70 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
14b80 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
14b90 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  d UTF-8.** strin
14ba0 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72  g of its 2nd par
14bb0 61 6d 65 74 65 72 2e 20 20 49 74 20 72 65 74 75  ameter.  It retu
14bc0 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  rns a result tab
14bd0 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  le to the.** poi
14be0 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
14bf0 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
14c00 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
14c10 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
14c20 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  n has finished u
14c30 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2c  sing the result,
14c40 20 69 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 70 61   it should.** pa
14c50 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ss the pointer t
14c60 6f 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  o the result tab
14c70 6c 65 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  le to sqlite3_fr
14c80 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
14c90 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
14ca0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
14cb0 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
14cc0 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
14cd0 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
14ce0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
14cf0 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
14d00 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
14d10 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
14d20 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
14d30 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
14d40 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
14d50 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
14d60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
14d70 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
14d80 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
14d90 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
14da0 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
14db0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
14dc0 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
14dd0 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
14de0 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
14df0 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
14e00 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
14e10 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
14e20 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
14e30 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
14e40 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
14e50 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
14e60 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
14e70 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
14e80 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
14e90 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
14ea0 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
14eb0 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
14ec0 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
14ed0 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
14ee0 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
14ef0 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
14f00 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
14f10 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
14f20 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
14f30 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
14f40 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
14f50 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
14f60 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  sg()]..**.** INV
14f70 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
14f80 48 31 32 33 37 31 7d 20 49 66 20 61 20 5b 73 71  H12371} If a [sq
14f90 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
14fa0 29 5d 20 66 61 69 6c 73 20 61 20 6d 65 6d 6f 72  )] fails a memor
14fb0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  y allocation, th
14fc0 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  en.**          i
14fd0 74 20 73 68 61 6c 6c 20 66 72 65 65 20 74 68 65  t shall free the
14fe0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 75 6e   result table un
14ff0 64 65 72 20 63 6f 6e 73 74 72 75 63 74 69 6f 6e  der construction
15000 2c 20 61 62 6f 72 74 20 74 68 65 0a 2a 2a 20 20  , abort the.**  
15010 20 20 20 20 20 20 20 20 71 75 65 72 79 20 69 6e          query in
15020 20 70 72 6f 63 65 73 73 2c 20 73 6b 69 70 20 61   process, skip a
15030 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 71 75  ny subsequent qu
15040 65 72 69 65 73 2c 20 73 65 74 20 74 68 65 0a 2a  eries, set the.*
15050 2a 20 20 20 20 20 20 20 20 20 20 2a 70 61 7a 52  *          *pazR
15060 65 73 75 6c 74 20 6f 75 74 70 75 74 20 70 6f 69  esult output poi
15070 6e 74 65 72 20 74 6f 20 4e 55 4c 4c 20 61 6e 64  nter to NULL and
15080 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
15090 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  NOMEM]..**.** {H
150a0 31 32 33 37 33 7d 20 49 66 20 74 68 65 20 70 6e  12373} If the pn
150b0 43 6f 6c 75 6d 6e 20 70 61 72 61 6d 65 74 65 72  Column parameter
150c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 67 65 74   to [sqlite3_get
150d0 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 6e 6f 74  _table()] is not
150e0 20 4e 55 4c 4c 0a 2a 2a 20 20 20 20 20 20 20 20   NULL.**        
150f0 20 20 74 68 65 6e 20 61 20 73 75 63 63 65 73 73    then a success
15100 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ful invocation o
15110 66 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  f [sqlite3_get_t
15120 61 62 6c 65 28 29 5d 20 73 68 61 6c 6c 0a 2a 2a  able()] shall.**
15130 20 20 20 20 20 20 20 20 20 20 77 72 69 74 65 20            write 
15140 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
15150 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
15160 20 20 20 20 20 20 20 20 20 72 65 73 75 6c 74 20           result 
15170 73 65 74 20 6f 66 20 74 68 65 20 71 75 65 72 79  set of the query
15180 20 69 6e 74 6f 20 2a 70 6e 43 6f 6c 75 6d 6e 2e   into *pnColumn.
15190 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 34 7d 20  .**.** {H12374} 
151a0 49 66 20 74 68 65 20 70 6e 52 6f 77 20 70 61 72  If the pnRow par
151b0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
151c0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
151d0 69 73 20 6e 6f 74 20 4e 55 4c 4c 0a 2a 2a 20 20  is not NULL.**  
151e0 20 20 20 20 20 20 20 20 74 68 65 6e 20 61 20 73          then a s
151f0 75 63 63 65 73 73 66 75 6c 20 69 6e 76 6f 63 61  uccessful invoca
15200 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
15210 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 73 68  _get_table()] sh
15220 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  all.**          
15230 77 72 69 74 65 73 20 74 68 65 20 6e 75 6d 62 65  writes the numbe
15240 72 20 6f 66 20 72 6f 77 73 20 69 6e 20 74 68 65  r of rows in the
15250 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 73  .**          res
15260 75 6c 74 20 73 65 74 20 6f 66 20 74 68 65 20 71  ult set of the q
15270 75 65 72 79 20 69 6e 74 6f 20 2a 70 6e 52 6f 77  uery into *pnRow
15280 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 33 37 36 7d  ..**.** {H12376}
15290 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
152a0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
152b0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
152c0 5d 20 74 68 61 74 20 63 6f 6d 70 75 74 65 73 0a  ] that computes.
152d0 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 20 72 6f  **          N ro
152e0 77 73 20 6f 66 20 72 65 73 75 6c 74 20 77 69 74  ws of result wit
152f0 68 20 43 20 63 6f 6c 75 6d 6e 73 20 70 65 72 20  h C columns per 
15300 72 6f 77 20 73 68 61 6c 6c 20 6d 61 6b 65 20 2a  row shall make *
15310 70 61 7a 52 65 73 75 6c 74 0a 2a 2a 20 20 20 20  pazResult.**    
15320 20 20 20 20 20 20 70 6f 69 6e 74 20 74 6f 20 61        point to a
15330 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
15340 65 72 73 20 74 6f 20 28 4e 2b 31 29 2a 43 20 73  ers to (N+1)*C s
15350 74 72 69 6e 67 73 20 77 68 65 72 65 20 74 68 65  trings where the
15360 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20 20 20   first.**       
15370 20 20 20 43 20 73 74 72 69 6e 67 73 20 61 72 65     C strings are
15380 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 61 73   column names as
15390 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a   obtained from.*
153a0 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
153b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
153c0 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 74 20  )] and the rest 
153d0 61 72 65 20 63 6f 6c 75 6d 6e 20 72 65 73 75 6c  are column resul
153e0 74 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20 20  t values.**     
153f0 20 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72       obtained fr
15400 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
15410 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
15420 2a 20 7b 48 31 32 33 37 39 7d 20 54 68 65 20 76  * {H12379} The v
15430 61 6c 75 65 73 20 69 6e 20 74 68 65 20 70 61 7a  alues in the paz
15440 52 65 73 75 6c 74 20 61 72 72 61 79 20 72 65 74  Result array ret
15450 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
15460 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 0a 2a  3_get_table()].*
15470 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c 6c  *          shall
15480 20 72 65 6d 61 69 6e 20 76 61 6c 69 64 20 75 6e   remain valid un
15490 74 69 6c 20 63 6c 65 61 72 65 64 20 62 79 20 5b  til cleared by [
154a0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
154b0 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  le()]..**.** {H1
154c0 32 33 38 32 7d 20 57 68 65 6e 20 61 6e 20 65 72  2382} When an er
154d0 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
154e0 67 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  g evaluation of 
154f0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
15500 6c 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  le()].**        
15510 20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 73    the function s
15520 68 61 6c 6c 20 73 65 74 20 2a 70 61 7a 52 65 73  hall set *pazRes
15530 75 6c 74 20 74 6f 20 4e 55 4c 4c 2c 20 77 72 69  ult to NULL, wri
15540 74 65 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  te an error mess
15550 61 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  age.**          
15560 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
15570 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
15580 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 6d 61  e3_malloc()], ma
15590 6b 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 2a  ke.**          *
155a0 2a 70 7a 45 72 72 6d 73 67 20 70 6f 69 6e 74 20  *pzErrmsg point 
155b0 74 6f 20 74 68 61 74 20 65 72 72 6f 72 20 6d 65  to that error me
155c0 73 73 61 67 65 2c 20 61 6e 64 20 72 65 74 75 72  ssage, and retur
155d0 6e 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  n a.**          
155e0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
155f0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74  or code]..*/.int
15600 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
15610 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
15620 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41  b,          /* A
15630 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
15640 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
15650 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51  *zSql,     /* SQ
15660 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
15670 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70  d */.  char ***p
15680 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20  azResult,    /* 
15690 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71  Results of the q
156a0 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  uery */.  int *p
156b0 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20  nRow,           
156c0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
156d0 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e  ult rows written
156e0 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   here */.  int *
156f0 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20  pnColumn,       
15700 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
15710 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69  sult columns wri
15720 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63  tten here */.  c
15730 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20  har **pzErrmsg  
15740 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
15750 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
15760 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  /.);.void sqlite
15770 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61  3_free_table(cha
15780 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a  r **result);../*
15790 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f  .** CAPI3REF: Fo
157a0 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50  rmatted String P
157b0 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e  rinting Function
157c0 73 20 7b 48 31 37 34 30 30 7d 20 3c 53 37 30 30  s {H17400} <S700
157d0 30 30 3e 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a  00><S20000>.**.*
157e0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
157f0 20 61 72 65 20 77 6f 72 6b 61 6c 69 6b 65 73 20   are workalikes 
15800 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
15810 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
15820 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
15830 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
15840 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rary..**.** The 
15850 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
15860 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d  ) and sqlite3_vm
15870 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
15880 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a  s write their.**
15890 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65   results into me
158a0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
158b0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
158c0 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  oc()]..** The st
158d0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
158e0 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
158f0 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
15900 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
15910 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
15920 20 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72   Both routines r
15930 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
15940 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
15950 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
15960 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
15970 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
15980 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
15990 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
159a0 67 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69  g..**.** In sqli
159b0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
159c0 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
159d0 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
159e0 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
159f0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
15a00 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
15a10 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
15a20 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
15a30 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
15a40 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
15a50 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
15a60 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
15a70 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
15a80 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
15a90 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
15aa0 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
15ab0 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
15ac0 73 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69  snprintf().  Thi
15ad0 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
15ae0 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
15af0 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
15b00 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
15b10 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
15b20 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
15b30 20 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74    Note also that
15b40 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
15b50 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
15b60 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
15b70 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
15b80 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
15b90 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
15ba0 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
15bb0 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20  nto the buffer. 
15bc0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a   We admit that.*
15bd0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
15be0 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74  characters writt
15bf0 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f  en would be a mo
15c00 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e  re useful return
15c10 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65  .** value but we
15c20 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
15c30 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
15c40 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
15c50 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77  rintf().** now w
15c60 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
15c70 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
15c80 2a 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20  *.** As long as 
15c90 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
15ca0 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
15cb0 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
15cc0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
15cd0 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
15ce0 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
15cf0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
15d00 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20  .  The first.** 
15d10 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73  parameter "n" is
15d20 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20   the total size 
15d30 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69  of the buffer, i
15d40 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66  ncluding space f
15d50 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74  or.** the zero t
15d60 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74  erminator.  So t
15d70 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e  he longest strin
15d80 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f  g that can be co
15d90 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74  mpletely.** writ
15da0 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20  ten will be n-1 
15db0 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
15dc0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
15dd0 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73   all implement s
15de0 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ome additional f
15df0 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74  ormatting.** opt
15e00 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
15e10 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75  eful for constru
15e20 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  cting SQL statem
15e30 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20  ents..** All of 
15e40 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66  the usual printf
15e50 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  () formatting op
15e60 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
15e70 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
15e80 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
15e90 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20   "%Q", and "%z" 
15ea0 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  options..**.** T
15eb0 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
15ec0 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
15ed0 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
15ee0 73 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61  s a null-termina
15ef0 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72  ted.** string fr
15f00 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  om the argument 
15f10 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c  list.  But %q al
15f20 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79  so doubles every
15f30 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e   '\'' character.
15f40 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e  .** %q is design
15f50 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
15f60 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  e a string liter
15f70 61 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  al.  By doubling
15f80 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
15f90 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
15fa0 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
15fb0 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
15fc0 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
15fd0 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
15fe0 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
15ff0 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65  mple, assume the
16000 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
16010 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20   zText contains 
16020 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
16030 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
16040 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
16050 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
16060 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
16070 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
16080 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
16090 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
160a0 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
160b0 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
160c0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
160d0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
160e0 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
160f0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
16100 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
16110 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
16120 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
16130 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
16140 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
16150 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
16160 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
16170 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
16180 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
16190 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
161a0 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
161b0 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
161c0 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
161d0 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
161e0 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
161f0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
16200 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
16210 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
16220 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
16230 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
16240 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
16250 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
16260 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
16270 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
16280 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
16290 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
162a0 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
162b0 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
162c0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
162d0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
162e0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
162f0 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
16300 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
16310 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
16320 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
16330 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
16340 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
16350 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
16360 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75  al rule you shou
16370 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  ld.** always use
16380 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
16390 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
163a0 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
163b0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  ing literal..**.
163c0 2a 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e  ** The %Q option
163d0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
163e0 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
163f0 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
16400 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
16410 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
16420 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64  tal string.  Add
16430 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68  itionally, if th
16440 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
16450 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c  he.** argument l
16460 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
16470 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
16480 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
16490 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a  NULL" (without.*
164a0 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29  * single quotes)
164b0 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
164c0 20 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c   %Q option.  So,
164d0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e   for example, on
164e0 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a  e could say:.**.
164f0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
16500 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
16510 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
16520 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
16530 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
16540 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  %Q)", zText);.**
16550 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
16560 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
16570 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
16580 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
16590 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
165a0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  >.**.** The code
165b0 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64   above will rend
165c0 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c  er a correct SQL
165d0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
165e0 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62  e zSQL.** variab
165f0 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a  le even if the z
16600 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73  Text variable is
16610 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
16620 0a 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20  .**.** The "%z" 
16630 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
16640 6e 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20  n works exactly 
16650 6c 69 6b 65 20 22 25 73 22 20 77 69 74 68 20 74  like "%s" with t
16660 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
16670 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
16680 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
16690 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
166a0 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
166b0 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
166c0 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
166d0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
166e0 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 49 4e  . {END}.**.** IN
166f0 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20  VARIANTS:.**.** 
16700 7b 48 31 37 34 30 33 7d 20 20 54 68 65 20 5b 73  {H17403}  The [s
16710 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
16720 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  ] and [sqlite3_v
16730 6d 70 72 69 6e 74 66 28 29 5d 20 69 6e 74 65 72  mprintf()] inter
16740 66 61 63 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  faces.**        
16750 20 20 20 72 65 74 75 72 6e 20 65 69 74 68 65 72     return either
16760 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
16770 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
16780 2d 38 20 73 74 72 69 6e 67 73 20 68 65 6c 64 20  -8 strings held 
16790 69 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  in.**           
167a0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
167b0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
167c0 6c 6c 6f 63 28 29 5d 20 6f 72 20 4e 55 4c 4c 20  lloc()] or NULL 
167d0 70 6f 69 6e 74 65 72 73 20 69 66 0a 2a 2a 20 20  pointers if.**  
167e0 20 20 20 20 20 20 20 20 20 61 20 63 61 6c 6c 20           a call 
167f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
16800 6f 63 28 29 5d 20 66 61 69 6c 73 2e 0a 2a 2a 0a  oc()] fails..**.
16810 2a 2a 20 7b 48 31 37 34 30 36 7d 20 20 54 68 65  ** {H17406}  The
16820 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
16830 74 66 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  tf()] interface 
16840 77 72 69 74 65 73 20 61 20 7a 65 72 6f 2d 74 65  writes a zero-te
16850 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 20 20 20 20  rminated.**     
16860 20 20 20 20 20 20 55 54 46 2d 38 20 73 74 72 69        UTF-8 stri
16870 6e 67 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  ng into the buff
16880 65 72 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  er pointed to by
16890 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
168a0 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 20 20 20  meter.**        
168b0 20 20 20 70 72 6f 76 69 64 65 64 20 74 68 61 74     provided that
168c0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
168d0 65 74 65 72 20 69 73 20 67 72 65 61 74 65 72 20  eter is greater 
168e0 74 68 61 6e 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  than zero..**.**
168f0 20 7b 48 31 37 34 30 37 7d 20 20 54 68 65 20 5b   {H17407}  The [
16900 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
16910 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  ()] interface do
16920 65 73 20 6e 6f 74 20 77 72 69 74 65 20 73 6c 6f  es not write slo
16930 74 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20  ts of.**        
16940 20 20 20 69 74 73 20 6f 75 74 70 75 74 20 62 75     its output bu
16950 66 66 65 72 20 28 74 68 65 20 73 65 63 6f 6e 64  ffer (the second
16960 20 70 61 72 61 6d 65 74 65 72 29 20 6f 75 74 73   parameter) outs
16970 69 64 65 20 74 68 65 20 72 61 6e 67 65 0a 2a 2a  ide the range.**
16980 20 20 20 20 20 20 20 20 20 20 20 6f 66 20 30 20             of 0 
16990 74 68 72 6f 75 67 68 20 4e 2d 31 20 28 77 68 65  through N-1 (whe
169a0 72 65 20 4e 20 69 73 20 74 68 65 20 66 69 72 73  re N is the firs
169b0 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  t parameter).** 
169c0 20 20 20 20 20 20 20 20 20 20 72 65 67 61 72 64            regard
169d0 6c 65 73 73 20 6f 66 20 74 68 65 20 6c 65 6e 67  less of the leng
169e0 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  th of the string
169f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 72 65  .**           re
16a00 71 75 65 73 74 65 64 20 62 79 20 74 68 65 20 66  quested by the f
16a10 6f 72 6d 61 74 20 73 70 65 63 69 66 69 63 61 74  ormat specificat
16a20 69 6f 6e 2e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71  ion..*/.char *sq
16a30 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
16a40 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
16a50 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
16a60 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
16a70 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68  r*, va_list);.ch
16a80 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
16a90 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
16aa0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
16ab0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
16ac0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
16ad0 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 20 7b  tion Subsystem {
16ae0 48 31 37 33 30 30 7d 20 3c 53 32 30 30 30 30 3e  H17300} <S20000>
16af0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
16b00 65 20 63 6f 72 65 20 20 75 73 65 73 20 74 68 65  e core  uses the
16b10 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
16b20 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
16b30 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
16b40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
16b50 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
16b60 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
16b70 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
16b80 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
16b90 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
16ba0 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
16bb0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
16bc0 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
16bd0 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
16be0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
16bf0 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
16c00 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ons..**.** The s
16c10 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
16c20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
16c30 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62  a pointer to a b
16c40 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  lock.** of memor
16c50 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  y at least N byt
16c60 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68  es in length, wh
16c70 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72  ere N is the par
16c80 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73 71  ameter..** If sq
16c90 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
16ca0 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61  s unable to obta
16cb0 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72  in sufficient fr
16cc0 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74  ee.** memory, it
16cd0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
16ce0 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 74 68 65  pointer.  If the
16cf0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a   parameter N to.
16d00 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
16d10 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e  c() is zero or n
16d20 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c  egative then sql
16d30 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65  ite3_malloc() re
16d40 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  turns.** a NULL 
16d50 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 43  pointer..**.** C
16d60 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
16d70 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
16d80 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
16d90 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
16da0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
16db0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
16dc0 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
16dd0 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
16de0 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
16df0 20 72 65 75 73 65 64 2e 20 20 54 68 65 20 73 71   reused.  The sq
16e00 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
16e10 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
16e20 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
16e30 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
16e40 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
16e50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
16e60 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
16e70 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
16e80 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
16e90 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
16ea0 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
16eb0 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
16ec0 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
16ed0 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
16ee0 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
16ef0 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
16f00 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
16f10 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
16f20 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
16f30 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
16f40 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
16f50 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
16f60 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
16f70 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
16f80 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
16f90 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
16fa0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
16fb0 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
16fc0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
16fd0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
16fe0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
16ff0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
17000 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74  e3_realloc() int
17010 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
17020 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
17030 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
17040 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20  cation to be at 
17050 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77  least N bytes, w
17060 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
17070 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17080 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  r.  The memory a
17090 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
170a0 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66  resized is the f
170b0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
170c0 72 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74  r.  If the first
170d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
170e0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
170f0 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
17100 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
17110 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
17120 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
17130 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
17140 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74  (N) where N is t
17150 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
17160 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
17170 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66 20  ealloc()..** If 
17180 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
17190 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
171a0 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  realloc() is zer
171b0 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65  o or.** negative
171c0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
171d0 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68  or is exactly th
171e0 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e  e same as callin
171f0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65  g.** sqlite3_fre
17200 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20  e(P) where P is 
17210 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
17220 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
17230 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71 6c  ealloc()..** sql
17240 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
17250 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
17260 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   to a memory all
17270 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74  ocation.** of at
17280 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
17290 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69  n size or NULL i
172a0 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  f sufficient mem
172b0 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62  ory is unavailab
172c0 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20 74  le..** If M is t
172d0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70  he size of the p
172e0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  rior allocation,
172f0 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62   then min(N,M) b
17300 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70  ytes.** of the p
17310 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
17320 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
17330 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
17340 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64   buffer returned
17350 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72  .** by sqlite3_r
17360 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65  ealloc() and the
17370 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
17380 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 49  n is freed..** I
17390 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
173a0 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  c() returns NULL
173b0 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72  , then the prior
173c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69   allocation.** i
173d0 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
173e0 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  ** The memory re
173f0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
17400 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73  3_malloc() and s
17410 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17420 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c  .** is always al
17430 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73  igned to at leas
17440 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e  t an 8 byte boun
17450 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  dary. {END}.**.*
17460 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 69 6d  * The default im
17470 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
17480 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
17490 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
174a0 75 73 65 73 0a 2a 2a 20 74 68 65 20 6d 61 6c 6c  uses.** the mall
174b0 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20  oc(), realloc() 
174c0 61 6e 64 20 66 72 65 65 28 29 20 70 72 6f 76 69  and free() provi
174d0 64 65 64 20 62 79 20 74 68 65 20 73 74 61 6e 64  ded by the stand
174e0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
174f0 2a 20 7b 48 31 37 33 38 32 7d 20 48 6f 77 65 76  * {H17382} Howev
17500 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73  er, if SQLite is
17510 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
17520 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 45 4d  he.** SQLITE_MEM
17530 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e 3c  ORY_SIZE=<i>NNN<
17540 2f 69 3e 20 43 20 70 72 65 70 72 6f 63 65 73 73  /i> C preprocess
17550 6f 72 20 6d 61 63 72 6f 20 28 77 68 65 72 65 20  or macro (where 
17560 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69 73  <i>NNN</i>.** is
17570 20 61 6e 20 69 6e 74 65 67 65 72 29 2c 20 74 68   an integer), th
17580 65 6e 20 53 51 4c 69 74 65 20 63 72 65 61 74 65  en SQLite create
17590 20 61 20 73 74 61 74 69 63 20 61 72 72 61 79 20   a static array 
175a0 6f 66 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 3c  of at least.** <
175b0 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73 20  i>NNN</i> bytes 
175c0 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 73 65 73  in size and uses
175d0 20 74 68 61 74 20 61 72 72 61 79 20 66 6f 72 20   that array for 
175e0 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
175f0 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ic.** memory all
17600 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 7b  ocation needs. {
17610 45 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e 61 6c  END}  Additional
17620 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
17630 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61 79  r options.** may
17640 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
17650 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  ure releases..**
17660 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
17670 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
17680 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
17690 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
176a0 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
176b0 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
176c0 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
176d0 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
176e0 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
176f0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
17700 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
17710 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
17720 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
17730 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
17740 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
17750 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
17760 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
17770 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f  .**.** The Windo
17780 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
17790 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74  layer calls.** t
177a0 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
177b0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
177c0 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
177d0 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
177e0 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
177f0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
17800 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
17810 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
17820 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
17830 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
17840 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
17850 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
17860 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
17870 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65  ation errors are
17880 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
17890 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72  * they are repor
178a0 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
178b0 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
178c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
178d0 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
178e0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
178f0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
17900 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 33 7d 20  .**.** {H17303} 
17910 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   The [sqlite3_ma
17920 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61  lloc(N)] interfa
17930 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65  ce returns eithe
17940 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  r a pointer to.*
17950 2a 20 20 20 20 20 20 20 20 20 20 20 61 20 6e 65  *           a ne
17960 77 6c 79 20 63 68 65 63 6b 65 64 2d 6f 75 74 20  wly checked-out 
17970 62 6c 6f 63 6b 20 6f 66 20 61 74 20 6c 65 61 73  block of at leas
17980 74 20 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  t N bytes of mem
17990 6f 72 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ory.**          
179a0 20 74 68 61 74 20 69 73 20 38 2d 62 79 74 65 20   that is 8-byte 
179b0 61 6c 69 67 6e 65 64 2c 20 6f 72 20 69 74 20 72  aligned, or it r
179c0 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69  eturns NULL if i
179d0 74 20 69 73 20 75 6e 61 62 6c 65 0a 2a 2a 20 20  t is unable.**  
179e0 20 20 20 20 20 20 20 20 20 74 6f 20 66 75 6c 66           to fulf
179f0 69 6c 6c 20 74 68 65 20 72 65 71 75 65 73 74 2e  ill the request.
17a00 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 30 34 7d 20  .**.** {H17304} 
17a10 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   The [sqlite3_ma
17a20 6c 6c 6f 63 28 4e 29 5d 20 69 6e 74 65 72 66 61  lloc(N)] interfa
17a30 63 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ce returns a NUL
17a40 4c 20 70 6f 69 6e 74 65 72 20 69 66 0a 2a 2a 20  L pointer if.** 
17a50 20 20 20 20 20 20 20 20 20 20 4e 20 69 73 20 6c            N is l
17a60 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
17a70 6c 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  l to zero..**.**
17a80 20 7b 48 31 37 33 30 35 7d 20 20 54 68 65 20 5b   {H17305}  The [
17a90 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 5d  sqlite3_free(P)]
17aa0 20 69 6e 74 65 72 66 61 63 65 20 72 65 6c 65 61   interface relea
17ab0 73 65 73 20 6d 65 6d 6f 72 79 20 70 72 65 76 69  ses memory previ
17ac0 6f 75 73 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  ously.**        
17ad0 20 20 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d     returned from
17ae0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
17af0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
17b00 72 65 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 20  realloc()],.**  
17b10 20 20 20 20 20 20 20 20 20 6d 61 6b 69 6e 67 20           making 
17b20 69 74 20 61 76 61 69 6c 61 62 6c 65 20 66 6f 72  it available for
17b30 20 72 65 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48   reuse..**.** {H
17b40 31 37 33 30 36 7d 20 20 41 20 63 61 6c 6c 20 74  17306}  A call t
17b50 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
17b60 4e 55 4c 4c 29 5d 20 69 73 20 61 20 68 61 72 6d  NULL)] is a harm
17b70 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
17b80 2a 20 7b 48 31 37 33 31 30 7d 20 20 41 20 63 61  * {H17310}  A ca
17b90 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
17ba0 65 61 6c 6c 6f 63 28 30 2c 4e 29 5d 20 69 73 20  ealloc(0,N)] is 
17bb0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20  equivalent to a 
17bc0 63 61 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20  call.**         
17bd0 20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61    to [sqlite3_ma
17be0 6c 6c 6f 63 28 4e 29 5d 2e 0a 2a 2a 0a 2a 2a 20  lloc(N)]..**.** 
17bf0 7b 48 31 37 33 31 32 7d 20 20 41 20 63 61 6c 6c  {H17312}  A call
17c00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   to [sqlite3_rea
17c10 6c 6c 6f 63 28 50 2c 30 29 5d 20 69 73 20 65 71  lloc(P,0)] is eq
17c20 75 69 76 61 6c 65 6e 74 20 74 6f 20 61 20 63 61  uivalent to a ca
17c30 6c 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ll.**           
17c40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
17c50 28 50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  (P)]..**.** {H17
17c60 33 31 35 7d 20 20 54 68 65 20 53 51 4c 69 74 65  315}  The SQLite
17c70 20 63 6f 72 65 20 75 73 65 73 20 5b 73 71 6c 69   core uses [sqli
17c80 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
17c90 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
17ca0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
17cb0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 72   and [sqlite3_fr
17cc0 65 65 28 29 5d 20 66 6f 72 20 61 6c 6c 20 6f 66  ee()] for all of
17cd0 20 69 74 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   its memory allo
17ce0 63 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 20 20  cation and.**   
17cf0 20 20 20 20 20 20 20 20 64 65 61 6c 6c 6f 63 61          dealloca
17d00 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  tion needs..**.*
17d10 2a 20 7b 48 31 37 33 31 38 7d 20 20 54 68 65 20  * {H17318}  The 
17d20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
17d30 28 50 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (P,N)] interface
17d40 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72 20   returns either 
17d50 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 20 20 20  a pointer.**    
17d60 20 20 20 20 20 20 20 74 6f 20 61 20 62 6c 6f 63         to a bloc
17d70 6b 20 6f 66 20 63 68 65 63 6b 65 64 2d 6f 75 74  k of checked-out
17d80 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65   memory of at le
17d90 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
17da0 69 7a 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ize.**          
17db0 20 74 68 61 74 20 69 73 20 38 2d 62 79 74 65 20   that is 8-byte 
17dc0 61 6c 69 67 6e 65 64 2c 20 6f 72 20 61 20 4e 55  aligned, or a NU
17dd0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
17de0 2a 20 7b 48 31 37 33 32 31 7d 20 20 57 68 65 6e  * {H17321}  When
17df0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
17e00 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73 20  c(P,N)] returns 
17e10 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
17e20 65 72 2c 20 69 74 20 66 69 72 73 74 0a 2a 2a 20  er, it first.** 
17e30 20 20 20 20 20 20 20 20 20 20 63 6f 70 69 65 73            copies
17e40 20 74 68 65 20 66 69 72 73 74 20 4b 20 62 79 74   the first K byt
17e50 65 73 20 6f 66 20 63 6f 6e 74 65 6e 74 20 66 72  es of content fr
17e60 6f 6d 20 50 20 69 6e 74 6f 20 74 68 65 20 6e 65  om P into the ne
17e70 77 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  wly.**          
17e80 20 61 6c 6c 6f 63 61 74 65 64 20 62 6c 6f 63 6b   allocated block
17e90 2c 20 77 68 65 72 65 20 4b 20 69 73 20 74 68 65  , where K is the
17ea0 20 6c 65 73 73 65 72 20 6f 66 20 4e 20 61 6e 64   lesser of N and
17eb0 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20   the size of.** 
17ec0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 62 75            the bu
17ed0 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ffer P..**.** {H
17ee0 31 37 33 32 32 7d 20 20 57 68 65 6e 20 5b 73 71  17322}  When [sq
17ef0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 50 2c  lite3_realloc(P,
17f00 4e 29 5d 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  N)] returns a no
17f10 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
17f20 69 74 20 66 69 72 73 74 0a 2a 2a 20 20 20 20 20  it first.**     
17f30 20 20 20 20 20 20 72 65 6c 65 61 73 65 73 20 74        releases t
17f40 68 65 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  he buffer P..**.
17f50 2a 2a 20 7b 48 31 37 33 32 33 7d 20 20 57 68 65  ** {H17323}  Whe
17f60 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  n [sqlite3_reall
17f70 6f 63 28 50 2c 4e 29 5d 20 72 65 74 75 72 6e 73  oc(P,N)] returns
17f80 20 4e 55 4c 4c 2c 20 74 68 65 20 62 75 66 66 65   NULL, the buffe
17f90 72 20 50 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  r P is.**       
17fa0 20 20 20 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64      not modified
17fb0 20 6f 72 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a   or released..**
17fc0 0a 2a 2a 20 41 53 53 55 4d 50 54 49 4f 4e 53 3a  .** ASSUMPTIONS:
17fd0 0a 2a 2a 0a 2a 2a 20 7b 41 31 37 33 35 30 7d 20  .**.** {A17350} 
17fe0 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   The pointer arg
17ff0 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74  uments to [sqlit
18000 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b  e3_free()] and [
18010 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
18020 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  )].**           
18030 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
18040 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
18050 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
18060 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 20 20  om a prior.**   
18070 20 20 20 20 20 20 20 20 69 6e 76 6f 63 61 74 69          invocati
18080 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
18090 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
180a0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
180b0 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 20 20 20  that have.**    
180c0 20 20 20 20 20 20 20 6e 6f 74 20 79 65 74 20 62         not yet b
180d0 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
180e0 0a 2a 2a 20 7b 41 31 37 33 35 31 7d 20 20 54 68  .** {A17351}  Th
180f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
18100 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
18110 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
18120 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 61 20  .**           a 
18130 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
18140 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
18150 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67  n released using
18160 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
18170 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
18180 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
18190 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
181a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
181b0 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
181c0 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
181d0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
181e0 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
181f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18200 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
18210 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 20 7b  tor Statistics {
18220 48 31 37 33 37 30 7d 20 3c 53 33 30 32 31 30 3e  H17370} <S30210>
18230 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72  .**.** SQLite pr
18240 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f  ovides these two
18250 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20   interfaces for 
18260 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65  reporting on the
18270 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68   status.** of th
18280 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
18290 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
182a0 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
182b0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
182c0 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69  ** routines, whi
182d0 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c  ch form the buil
182e0 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
182f0 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
18300 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
18310 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37  TS:.**.** {H1737
18320 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
18330 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
18340 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
18350 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
18360 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  es.**          o
18370 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
18380 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
18390 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
183a0 20 66 72 65 65 64 29 2e 0a 2a 2a 0a 2a 2a 20 7b   freed)..**.** {
183b0 48 31 37 33 37 33 7d 20 54 68 65 20 5b 73 71 6c  H17373} The [sql
183c0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
183d0 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
183e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
183f0 69 6d 75 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20  imum.**         
18400 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
18410 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
18420 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
18430 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20  -water mark.**  
18440 20 20 20 20 20 20 20 20 77 61 73 20 6c 61 73 74          was last
18450 20 72 65 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48   reset..**.** {H
18460 31 37 33 37 34 7d 20 54 68 65 20 76 61 6c 75 65  17374} The value
18470 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
18480 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
18490 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  ed()] and.**    
184a0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 6d        [sqlite3_m
184b0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
184c0 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
184d0 76 65 72 68 65 61 64 0a 2a 2a 20 20 20 20 20 20  verhead.**      
184e0 20 20 20 20 61 64 64 65 64 20 62 79 20 53 51 4c      added by SQL
184f0 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65  ite in its imple
18500 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71  mentation of [sq
18510 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
18520 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 75 74  .**          but
18530 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
18540 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
18550 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
18560 20 6c 69 62 72 61 72 79 0a 2a 2a 20 20 20 20 20   library.**     
18570 20 20 20 20 20 72 6f 75 74 69 6e 65 73 20 74 68       routines th
18580 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  at [sqlite3_mall
18590 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a  oc()] may call..
185a0 2a 2a 0a 2a 2a 20 7b 48 31 37 33 37 35 7d 20 54  **.** {H17375} T
185b0 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77  he memory high-w
185c0 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73  ater mark is res
185d0 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e  et to the curren
185e0 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 20 20  t value of.**   
185f0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
18600 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69  memory_used()] i
18610 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
18620 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  e parameter to.*
18630 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
18640 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
18650 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
18660 20 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75    The value retu
18670 72 6e 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  rned.**         
18680 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
18690 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
186a0 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
186b0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 20 20 20 20  ter mark.**     
186c0 20 20 20 20 20 70 72 69 6f 72 20 74 6f 20 74 68       prior to th
186d0 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69  e reset..*/.sqli
186e0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
186f0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
18700 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
18710 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
18720 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
18730 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
18740 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
18750 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
18760 72 20 47 65 6e 65 72 61 74 6f 72 20 7b 48 31 37  r Generator {H17
18770 33 39 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a  390} <S20000>.**
18780 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
18790 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
187a0 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
187b0 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
187c0 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
187d0 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
187e0 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
187f0 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
18800 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
18810 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
18820 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
18830 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
18840 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
18850 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
18860 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
18870 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
18880 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
18890 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
188a0 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
188b0 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
188c0 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
188d0 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
188e0 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
188f0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  ses..**.** A cal
18900 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
18910 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
18920 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
18930 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
18940 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 74 69  .** The first ti
18950 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  me this routine 
18960 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68  is invoked (eith
18970 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72  er internally or
18980 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   by.** the appli
18990 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47  cation) the PRNG
189a0 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67   is seeded using
189b0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
189c0 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ined.** from the
189d0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
189e0 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
189f0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
18a00 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61   object..** On a
18a10 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ll subsequent in
18a20 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70  vocations, the p
18a30 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73  seudo-randomness
18a40 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a   is generated.**
18a50 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20   internally and 
18a60 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65  without recourse
18a70 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
18a80 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73  _vfs] xRandomnes
18a90 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a  s.** method..**.
18aa0 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a  ** INVARIANTS:.*
18ab0 2a 0a 2a 2a 20 7b 48 31 37 33 39 32 7d 20 54 68  *.** {H17392} Th
18ac0 65 20 5b 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  e [sqlite3_rando
18ad0 6d 6e 65 73 73 28 4e 2c 50 29 5d 20 69 6e 74 65  mness(N,P)] inte
18ae0 72 66 61 63 65 20 77 72 69 74 65 73 20 4e 20 62  rface writes N b
18af0 79 74 65 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20  ytes of.**      
18b00 20 20 20 20 68 69 67 68 2d 71 75 61 6c 69 74 79      high-quality
18b10 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
18b20 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
18b30 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
18b40 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
18b50 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
18b60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
18b70 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
18b80 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
18b90 63 6b 73 20 7b 48 31 32 35 30 30 7d 20 3c 53 37  cks {H12500} <S7
18ba0 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0100>.**.** This
18bb0 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
18bc0 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20  rs a authorizer 
18bd0 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
18be0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
18bf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18c00 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
18c10 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
18c20 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68  ent..** The auth
18c30 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
18c40 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
18c50 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
18c60 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
18c70 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
18c80 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
18c90 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
18ca0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
18cb0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
18cc0 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b  epare16()] and [
18cd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
18ce0 36 5f 76 32 28 29 5d 2e 20 20 41 74 20 76 61 72  6_v2()].  At var
18cf0 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
18d00 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
18d10 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
18d20 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
18d30 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
18d40 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
18d50 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
18d60 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
18d70 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
18d80 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
18d90 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
18da0 64 2e 20 20 54 68 65 20 61 75 74 68 6f 72 69 7a  d.  The authoriz
18db0 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
18dc0 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
18dd0 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
18de0 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
18df0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
18e00 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
18e10 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
18e20 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
18e30 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
18e40 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
18e50 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
18e60 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
18e70 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
18e80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
18e90 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
18ea0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
18eb0 20 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   If the authoriz
18ec0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
18ed0 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
18ee0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
18ef0 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
18f00 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
18f10 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
18f20 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
18f30 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
18f40 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
18f50 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
18f60 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
18f70 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
18f80 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
18f90 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
18fa0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
18fb0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
18fc0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
18fd0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
18fe0 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 57 68  ested is ok.  Wh
18ff0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
19000 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
19010 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
19020 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
19030 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
19040 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
19050 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
19060 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
19070 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
19080 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
19090 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
190a0 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 20 49  ss is denied.  I
190b0 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  f the authorizer
190c0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
190d0 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
190e0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
190f0 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
19100 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
19110 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
19120 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
19130 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
19140 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
19150 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
19160 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
19170 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
19180 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
19190 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
191a0 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
191b0 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
191c0 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
191d0 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
191e0 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
191f0 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
19200 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
19210 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
19220 20 74 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   table..**.** Th
19230 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
19240 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
19250 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
19260 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
19270 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
19280 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
19290 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
192a0 20 69 6e 74 65 72 66 61 63 65 2e 20 54 68 65 20   interface. The 
192b0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
192c0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
192d0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
192e0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
192f0 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
19300 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
19310 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
19320 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
19330 6f 72 69 7a 65 64 2e 20 54 68 65 20 74 68 69 72  orized. The thir
19340 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
19350 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
19360 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
19370 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
19380 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
19390 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
193a0 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
193b0 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
193c0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
193d0 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
193e0 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
193f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19400 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
19410 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
19420 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
19430 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
19440 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
19450 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
19460 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
19470 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
19480 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
19490 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
194a0 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
194b0 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
194c0 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
194d0 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
194e0 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
194f0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
19500 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
19510 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
19520 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
19530 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
19540 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
19550 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
19560 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
19570 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
19580 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
19590 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
195a0 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
195b0 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
195c0 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
195d0 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
195e0 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
195f0 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
19600 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
19610 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
19620 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
19630 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
19640 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
19650 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
19660 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
19670 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
19680 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
19690 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
196a0 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
196b0 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
196c0 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
196d0 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
196e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
196f0 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
19700 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
19710 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
19720 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
19730 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
19740 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
19750 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
19760 2a 2a 0a 2a 2a 20 4f 6e 6c 79 20 61 20 73 69 6e  **.** Only a sin
19770 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  gle authorizer c
19780 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f  an be in place o
19790 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  n a database con
197a0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20  nection.** at a 
197b0 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c  time.  Each call
197c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
197d0 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72  authorizer overr
197e0 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76  ides the.** prev
197f0 69 6f 75 73 20 63 61 6c 6c 2e 20 20 44 69 73 61  ious call.  Disa
19800 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
19810 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
19820 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
19830 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
19840 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
19850 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
19860 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
19870 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
19880 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
19890 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
198a0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
198b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
198c0 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68  invoked the auth
198d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e  orizer callback.
198e0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
198f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
19900 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
19910 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
19920 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
19930 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19940 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
19950 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
19960 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
19970 68 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 5b 73  h..**.** When [s
19980 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
19990 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  2()] is used to 
199a0 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
199b0 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74  ent, the.** stat
199c0 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72  ement might be r
199d0 65 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67  eprepared during
199e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
199f0 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73  ] due to a .** s
19a00 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48  chema change.  H
19a10 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63  ence, the applic
19a20 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73  ation should ens
19a30 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
19a40 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a  correct authoriz
19a50 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61  er callback rema
19a60 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72  ins in place dur
19a70 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
19a80 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
19a90 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
19aa0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
19ab0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
19ac0 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
19ad0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
19ae0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
19af0 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
19b00 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
19b10 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
19b20 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
19b30 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
19b40 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ()]..**.** INVAR
19b50 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
19b60 32 35 30 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  2501} The [sqlit
19b70 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
19b80 72 28 44 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  r(D,...)] interf
19b90 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 0a  ace registers a.
19ba0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 68  **          auth
19bb0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
19bc0 77 69 74 68 20 64 61 74 61 62 61 73 65 20 63 6f  with database co
19bd0 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 0a 2a  nnection D..**.*
19be0 2a 20 7b 48 31 32 35 30 32 7d 20 54 68 65 20 61  * {H12502} The a
19bf0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
19c00 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
19c10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
19c20 61 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  are.**          
19c30 62 65 69 6e 67 20 70 61 72 73 65 65 64 20 61 6e  being parseed an
19c40 64 20 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  d compiled..**.*
19c50 2a 20 7b 48 31 32 35 30 33 7d 20 49 66 20 74 68  * {H12503} If th
19c60 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
19c70 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 6e  lback returns an
19c80 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
19c90 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  an.**          [
19ca0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
19cb0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
19cc0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
19cd0 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  hen.**          
19ce0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
19cf0 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20 74  interface call t
19d00 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 20 20  hat caused.**   
19d10 20 20 20 20 20 20 20 74 68 65 20 61 75 74 68 6f         the autho
19d20 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 74  rizer callback t
19d30 6f 20 72 75 6e 20 73 68 61 6c 6c 20 66 61 69 6c  o run shall fail
19d40 20 77 69 74 68 20 61 6e 0a 2a 2a 20 20 20 20 20   with an.**     
19d50 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
19d60 4f 52 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61  OR] error code a
19d70 6e 64 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  nd an appropriat
19d80 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
19d90 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30 34 7d 20  .**.** {H12504} 
19da0 57 68 65 6e 20 74 68 65 20 61 75 74 68 6f 72 69  When the authori
19db0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
19dc0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
19dd0 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  , the operation.
19de0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 73 63  **          desc
19df0 72 69 62 65 64 20 69 73 20 70 72 6f 63 65 73 73  ribed is process
19e00 65 64 20 6e 6f 72 6d 61 6c 6c 79 2e 0a 2a 2a 0a  ed normally..**.
19e10 2a 2a 20 7b 48 31 32 35 30 35 7d 20 57 68 65 6e  ** {H12505} When
19e20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
19e30 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
19e40 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
19e50 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
19e60 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 74 65  application inte
19e70 72 66 61 63 65 20 63 61 6c 6c 20 74 68 61 74 20  rface call that 
19e80 63 61 75 73 65 64 20 74 68 65 0a 2a 2a 20 20 20  caused the.**   
19e90 20 20 20 20 20 20 20 61 75 74 68 6f 72 69 7a 65         authorize
19ea0 72 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 72 75  r callback to ru
19eb0 6e 20 73 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20  n shall fail.** 
19ec0 20 20 20 20 20 20 20 20 20 77 69 74 68 20 61 6e           with an
19ed0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
19ee0 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 61  error code and a
19ef0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a  n error message.
19f00 2a 2a 20 20 20 20 20 20 20 20 20 20 65 78 70 6c  **          expl
19f10 61 69 6e 69 6e 67 20 74 68 61 74 20 61 63 63 65  aining that acce
19f20 73 73 20 69 73 20 64 65 6e 69 65 64 2e 0a 2a 2a  ss is denied..**
19f30 0a 2a 2a 20 7b 48 31 32 35 30 36 7d 20 49 66 20  .** {H12506} If 
19f40 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
19f50 6f 64 65 20 28 74 68 65 20 32 6e 64 20 70 61 72  ode (the 2nd par
19f60 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
19f70 74 68 6f 72 69 7a 65 72 0a 2a 2a 20 20 20 20 20  thorizer.**     
19f80 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 29 20 69       callback) i
19f90 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20  s [SQLITE_READ] 
19fa0 61 6e 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  and the authoriz
19fb0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
19fc0 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rns.**          
19fd0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
19fe0 20 74 68 65 6e 20 74 68 65 20 70 72 65 70 61 72   then the prepar
19ff0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
1a000 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 0a 2a  constructed to.*
1a010 2a 20 20 20 20 20 20 20 20 20 20 69 6e 73 65 72  *          inser
1a020 74 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  t a NULL value i
1a030 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
1a040 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
1a050 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 20   would have.**  
1a060 20 20 20 20 20 20 20 20 62 65 65 6e 20 72 65 61          been rea
1a070 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  d if [SQLITE_OK]
1a080 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e   had been return
1a090 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 30  ed..**.** {H1250
1a0a0 37 7d 20 49 66 20 74 68 65 20 61 75 74 68 6f 72  7} If the author
1a0b0 69 7a 65 72 20 63 6f 64 65 20 28 74 68 65 20 32  izer code (the 2
1a0c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
1a0d0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 0a 2a  the authorizer.*
1a0e0 2a 20 20 20 20 20 20 20 20 20 20 63 61 6c 6c 62  *          callb
1a0f0 61 63 6b 29 20 69 73 20 61 6e 79 74 68 69 6e 67  ack) is anything
1a100 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
1a110 49 54 45 5f 52 45 41 44 5d 2c 20 74 68 65 6e 0a  ITE_READ], then.
1a120 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20 72 65  **          a re
1a130 74 75 72 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  turn of [SQLITE_
1a140 49 47 4e 4f 52 45 5d 20 68 61 73 20 74 68 65 20  IGNORE] has the 
1a150 73 61 6d 65 20 65 66 66 65 63 74 20 61 73 20 5b  same effect as [
1a160 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2e 0a 2a 2a  SQLITE_DENY]..**
1a170 0a 2a 2a 20 7b 48 31 32 35 31 30 7d 20 54 68 65  .** {H12510} The
1a180 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1a190 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1a1a0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
1a1b0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 20 20 20 20   copy of.**     
1a1c0 20 20 20 20 20 74 68 65 20 74 68 69 72 64 20 70       the third p
1a1d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1a1e0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1a1f0 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
1a200 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  face..**.** {H12
1a210 35 31 31 7d 20 54 68 65 20 73 65 63 6f 6e 64 20  511} The second 
1a220 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1a230 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1a240 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20 20 20 20  integer.**      
1a250 20 20 20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59      [SQLITE_COPY
1a260 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
1a270 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
1a280 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
1a290 74 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  tion.**         
1a2a0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
1a2b0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 31 32  d..**.** {H12512
1a2c0 7d 20 54 68 65 20 74 68 69 72 64 20 74 68 72 6f  } The third thro
1a2d0 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
1a2e0 74 65 72 73 20 74 6f 20 74 68 65 20 63 61 6c 6c  ters to the call
1a2f0 62 61 63 6b 20 61 72 65 0a 2a 2a 20 20 20 20 20  back are.**     
1a300 20 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e       zero-termin
1a310 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1a320 74 20 63 6f 6e 74 61 69 6e 0a 2a 2a 20 20 20 20  t contain.**    
1a330 20 20 20 20 20 20 61 64 64 69 74 69 6f 6e 61 6c        additional
1a340 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
1a350 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
1a360 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
1a370 2a 20 7b 48 31 32 35 32 30 7d 20 45 61 63 68 20  * {H12520} Each 
1a380 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
1a390 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1a3a0 29 5d 20 6f 76 65 72 72 69 64 65 73 0a 2a 2a 20  )] overrides.** 
1a3b0 20 20 20 20 20 20 20 20 20 61 6e 79 20 70 72 65           any pre
1a3c0 76 69 6f 75 73 6c 79 20 69 6e 73 74 61 6c 6c 65  viously installe
1a3d0 64 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a  d authorizer..**
1a3e0 0a 2a 2a 20 7b 48 31 32 35 32 31 7d 20 41 20 4e  .** {H12521} A N
1a3f0 55 4c 4c 20 61 75 74 68 6f 72 69 7a 65 72 20 6d  ULL authorizer m
1a400 65 61 6e 73 20 74 68 61 74 20 6e 6f 20 61 75 74  eans that no aut
1a410 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 20 20  horization.**   
1a420 20 20 20 20 20 20 20 63 61 6c 6c 62 61 63 6b 20         callback 
1a430 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
1a440 2a 20 7b 48 31 32 35 32 32 7d 20 54 68 65 20 64  * {H12522} The d
1a450 65 66 61 75 6c 74 20 61 75 74 68 6f 72 69 7a 65  efault authorize
1a460 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e  r is NULL..*/.in
1a470 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
1a480 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
1a490 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
1a4a0 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
1a4b0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1a4c0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1a4d0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
1a4e0 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
1a4f0 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
1a500 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
1a510 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b  r Return Codes {
1a520 48 31 32 35 39 30 7d 20 3c 48 31 32 35 30 30 3e  H12590} <H12500>
1a530 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1a540 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1a550 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
1a560 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1a570 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
1a580 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
1a590 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
1a5a0 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
1a5b0 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
1a5c0 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
1a5d0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1a5e0 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
1a5f0 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
1a600 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
1a610 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
1a620 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
1a630 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
1a640 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
1a650 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e  ation..*/.#defin
1a660 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
1a670 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
1a680 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
1a690 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
1a6a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1a6b0 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
1a6c0 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
1a6d0 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
1a6e0 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
1a6f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a700 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
1a710 6f 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 35 30  on Codes {H12550
1a720 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a  } <H12500>.**.**
1a730 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
1a740 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
1a750 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
1a760 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
1a770 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
1a780 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
1a790 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
1a7a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
1a7b0 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
1a7c0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1a7d0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1a7e0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
1a7f0 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
1a800 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
1a810 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
1a820 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
1a830 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
1a840 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
1a850 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
1a860 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
1a870 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
1a880 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
1a890 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
1a8a0 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
1a8b0 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
1a8c0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
1a8d0 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
1a8e0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
1a8f0 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
1a900 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
1a910 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
1a920 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
1a930 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
1a940 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
1a950 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
1a960 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1a970 65 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70  eter.  The 5th p
1a980 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
1a990 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
1a9a0 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
1a9b0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
1a9c0 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
1a9d0 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  p",.** etc.) if 
1a9e0 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65  applicable.  The
1a9f0 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
1aa00 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
1aa10 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
1aa20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1aa30 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
1aa40 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
1aa50 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
1aa60 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
1aa70 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
1aa80 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
1aa90 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
1aaa0 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
1aab0 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
1aac0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
1aad0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 31 7d  :.**.** {H12551}
1aae0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
1aaf0 6d 65 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 20  meter to an.**  
1ab00 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1ab10 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1ab20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
1ab30 6c 62 61 63 6b 5d 20 73 68 61 6c 6c 20 62 65 20  lback] shall be 
1ab40 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 20 20  an integer.**   
1ab50 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 43         [SQLITE_C
1ab60 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  OPY | authorizer
1ab70 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
1ab80 69 66 69 65 73 20 77 68 61 74 20 61 63 74 69 6f  ifies what actio
1ab90 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  n.**          is
1aba0 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65   being authorize
1abb0 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 35 35 32  d..**.** {H12552
1abc0 7d 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74  } The 3rd and 4t
1abd0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
1abe0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1abf0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1ac00 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1ac10 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  ization callback
1ac20 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  ].**          sh
1ac30 61 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  all be parameter
1ac40 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
1ac50 69 6e 67 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20  ing on which.** 
1ac60 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
1ac70 5f 43 4f 50 59 20 7c 20 61 75 74 68 6f 72 69 7a  _COPY | authoriz
1ac80 65 72 20 63 6f 64 65 5d 20 69 73 20 75 73 65 64  er code] is used
1ac90 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1aca0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1acb0 7b 48 31 32 35 35 33 7d 20 54 68 65 20 35 74 68  {H12553} The 5th
1acc0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1acd0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
1ace0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1acf0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1ad00 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 73 68 61  er callback] sha
1ad10 6c 6c 20 62 65 20 74 68 65 20 6e 61 6d 65 0a 2a  ll be the name.*
1ad20 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
1ad30 65 20 64 61 74 61 62 61 73 65 20 28 65 78 61 6d  e database (exam
1ad40 70 6c 65 3a 20 22 6d 61 69 6e 22 2c 20 22 74 65  ple: "main", "te
1ad50 6d 70 22 2c 20 65 74 63 2e 29 20 69 66 20 61 70  mp", etc.) if ap
1ad60 70 6c 69 63 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  plicable..**.** 
1ad70 7b 48 31 32 35 35 34 7d 20 54 68 65 20 36 74 68  {H12554} The 6th
1ad80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1ad90 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
1ada0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1adb0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1adc0 65 72 20 63 61 6c 6c 62 61 63 6b 5d 20 73 68 61  er callback] sha
1add0 6c 6c 20 62 65 20 74 68 65 20 6e 61 6d 65 0a 2a  ll be the name.*
1ade0 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 74 68  *          of th
1adf0 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
1ae00 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
1ae10 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
1ae20 20 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20   for.**         
1ae30 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
1ae40 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
1ae50 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
1ae60 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
1ae70 72 6f 6d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  rom.**          
1ae80 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
1ae90 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
1aea0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1aeb0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1aec0 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
1aed0 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
1aee0 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
1aef0 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
1af00 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
1af10 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1af20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1af30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1af40 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
1af50 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
1af60 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1af70 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1af80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1af90 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
1afa0 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
1afb0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1afc0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1afd0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1afe0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
1aff0 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
1b000 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1b010 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1b020 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b030 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
1b040 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
1b050 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1b060 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1b070 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b080 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
1b090 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
1b0a0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1b0b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1b0c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1b0d0 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
1b0e0 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
1b0f0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1b100 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1b110 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1b120 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
1b130 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
1b140 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1b150 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1b160 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
1b170 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
1b180 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
1b190 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1b1a0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1b1b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1b1c0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
1b1d0 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
1b1e0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1b1f0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1b200 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1b210 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
1b220 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
1b230 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1b240 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1b250 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1b260 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
1b270 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
1b280 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1b290 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1b2a0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1b2b0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
1b2c0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1b2d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1b2e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b2f0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1b300 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
1b310 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1b320 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1b330 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b340 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1b350 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
1b360 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1b370 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1b380 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b390 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
1b3a0 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
1b3b0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1b3c0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1b3d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b3e0 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
1b3f0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
1b400 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1b410 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b420 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b430 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
1b440 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
1b450 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b460 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1b470 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b480 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
1b490 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
1b4a0 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
1b4b0 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
1b4c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b4d0 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
1b4e0 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
1b4f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
1b500 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
1b510 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b520 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
1b530 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
1b540 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
1b550 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1b560 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b570 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
1b580 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
1b590 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
1b5a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1b5b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
1b5c0 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
1b5d0 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
1b5e0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
1b5f0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
1b600 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
1b610 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
1b620 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
1b630 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
1b640 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1b650 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
1b660 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
1b670 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
1b680 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
1b690 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1b6a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
1b6b0 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
1b6c0 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
1b6d0 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
1b6e0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1b6f0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
1b700 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
1b710 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
1b720 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1b730 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1b740 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
1b750 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
1b760 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
1b770 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1b780 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1b790 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1b7a0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
1b7b0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1b7c0 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
1b7d0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1b7e0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
1b7f0 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
1b800 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1b810 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
1b820 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b830 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
1b840 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
1b850 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
1b860 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
1b870 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
1b880 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
1b890 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
1b8a0 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
1b8b0 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
1b8c0 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
1b8d0 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
1b8e0 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
1b8f0 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
1b900 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1b910 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
1b920 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
1b930 69 6f 6e 73 20 7b 48 31 32 32 38 30 7d 20 3c 53  ions {H12280} <S
1b940 36 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  60400>.** EXPERI
1b950 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65  MENTAL.**.** The
1b960 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
1b970 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
1b980 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
1b990 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
1b9a0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
1b9b0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
1b9c0 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
1b9d0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ments..**.** The
1b9e0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1b9f0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
1ba00 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1ba10 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
1ba20 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
1ba30 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
1ba40 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
1ba50 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
1ba60 74 65 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 63  tep()]..** The c
1ba70 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1ba80 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
1ba90 67 20 6f 66 20 74 68 65 20 53 51 4c 20 73 74 61  g of the SQL sta
1baa0 74 65 6d 65 6e 74 20 74 65 78 74 0a 2a 2a 20 61  tement text.** a
1bab0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1bac0 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
1bad0 63 75 74 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  cuting.  Additio
1bae0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 6f 63  nal callbacks oc
1baf0 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
1bb00 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
1bb10 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
1bb20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
1bb30 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
1bb40 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
1bb50 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
1bb60 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
1bb70 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  rigger..**.** Th
1bb80 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1bb90 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1bba0 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
1bbb0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
1bbc0 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
1bbd0 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
1bbe0 2e 20 20 54 68 65 20 70 72 6f 66 69 6c 65 20 63  .  The profile c
1bbf0 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
1bc00 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
1bc10 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
1bc20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
1bc30 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
1bc40 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
1bc50 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
1bc60 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a   took to run..**
1bc70 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a  .** INVARIANTS:.
1bc80 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 31 7d 20 54  **.** {H12281} T
1bc90 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1bca0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
1bcb0 62 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  by [sqlite3_trac
1bcc0 65 28 29 5d 20 0a 2a 2a 20 20 20 20 20 20 20 20  e()] .**        
1bcd0 20 20 73 68 61 6c 6c 20 62 65 20 69 6e 76 6f 6b    shall be invok
1bce0 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77  ed.**          w
1bcf0 68 65 6e 65 76 65 72 20 61 6e 20 53 51 4c 20 73  henever an SQL s
1bd00 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
1bd10 65 67 69 6e 73 20 74 6f 20 65 78 65 63 75 74 65  egins to execute
1bd20 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
1bd30 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 69 67   whenever a trig
1bd40 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d 20 66  ger subprogram f
1bd50 69 72 73 74 20 62 65 67 69 6e 73 20 74 6f 20 72  irst begins to r
1bd60 75 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38  un..**.** {H1228
1bd70 32 7d 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  2} Each call to 
1bd80 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
1bd90 5d 20 73 68 61 6c 6c 20 6f 76 65 72 72 69 64 65  ] shall override
1bda0 20 74 68 65 20 70 72 65 76 69 6f 75 73 6c 79 0a   the previously.
1bdb0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67 69  **          regi
1bdc0 73 74 65 72 65 64 20 74 72 61 63 65 20 63 61 6c  stered trace cal
1bdd0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  lback..**.** {H1
1bde0 32 32 38 33 7d 20 41 20 4e 55 4c 4c 20 74 72 61  2283} A NULL tra
1bdf0 63 65 20 63 61 6c 6c 62 61 63 6b 20 73 68 61 6c  ce callback shal
1be00 6c 20 64 69 73 61 62 6c 65 20 74 72 61 63 69 6e  l disable tracin
1be10 67 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38 34  g..**.** {H12284
1be20 7d 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  } The first argu
1be30 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63  ment to the trac
1be40 65 20 63 61 6c 6c 62 61 63 6b 20 73 68 61 6c 6c  e callback shall
1be50 20 62 65 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   be a copy of.**
1be60 20 20 20 20 20 20 20 20 20 20 74 68 65 20 70 6f            the po
1be70 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
1be80 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  the 3rd argument
1be90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61   to [sqlite3_tra
1bea0 63 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ce()]..**.** {H1
1beb0 32 32 38 35 7d 20 54 68 65 20 73 65 63 6f 6e 64  2285} The second
1bec0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
1bed0 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
1bee0 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  is a.**         
1bef0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1bf00 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 63 6f   UTF-8 string co
1bf10 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6f 72 69  ntaining the ori
1bf20 67 69 6e 61 6c 20 74 65 78 74 0a 2a 2a 20 20 20  ginal text.**   
1bf30 20 20 20 20 20 20 20 6f 66 20 74 68 65 20 53 51         of the SQ
1bf40 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 69  L statement as i
1bf50 74 20 77 61 73 20 70 61 73 73 65 64 20 69 6e 74  t was passed int
1bf60 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
1bf70 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 20 20 20 20  re_v2()].**     
1bf80 20 20 20 20 20 6f 72 20 74 68 65 20 65 71 75 69       or the equi
1bf90 76 61 6c 65 6e 74 2c 20 6f 72 20 61 6e 20 53 51  valent, or an SQ
1bfa0 4c 20 63 6f 6d 6d 65 6e 74 20 69 6e 64 69 63 61  L comment indica
1bfb0 74 69 6e 67 20 74 68 65 20 62 65 67 69 6e 6e 69  ting the beginni
1bfc0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ng.**          o
1bfd0 66 20 61 20 74 72 69 67 67 65 72 20 73 75 62 70  f a trigger subp
1bfe0 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  rogram..**.** {H
1bff0 31 32 32 38 37 7d 20 54 68 65 20 63 61 6c 6c 62  12287} The callb
1c000 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1c010 69 73 74 65 72 65 64 20 62 79 20 5b 73 71 6c 69  istered by [sqli
1c020 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 69  te3_profile()] i
1c030 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 20 20 20  s invoked.**    
1c040 20 20 20 20 20 20 61 73 20 65 61 63 68 20 53 51        as each SQ
1c050 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
1c060 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  shes..**.** {H12
1c070 32 38 38 7d 20 54 68 65 20 66 69 72 73 74 20 70  288} The first p
1c080 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1c090 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
1c0a0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a   is a copy of.**
1c0b0 20 20 20 20 20 20 20 20 20 20 74 68 65 20 33 72            the 3r
1c0c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
1c0d0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1c0e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 32 38  )]..**.** {H1228
1c0f0 39 7d 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  9} The second pa
1c100 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 70  rameter to the p
1c110 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
1c120 69 73 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20  is a.**         
1c130 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1c140 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
1c150 61 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  at contains the 
1c160 63 6f 6d 70 6c 65 74 65 20 74 65 78 74 20 6f 66  complete text of
1c170 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
1c180 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1c190 73 20 69 74 20 77 61 73 20 70 72 6f 63 65 73 73  s it was process
1c1a0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ed by [sqlite3_p
1c1b0 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a 20  repare_v2()].** 
1c1c0 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
1c1d0 65 71 75 69 76 61 6c 65 6e 74 2e 0a 2a 2a 0a 2a  equivalent..**.*
1c1e0 2a 20 7b 48 31 32 32 39 30 7d 20 54 68 65 20 74  * {H12290} The t
1c1f0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
1c200 6f 20 74 68 65 20 70 72 6f 66 69 6c 65 20 63 61  o the profile ca
1c210 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 65 73 74  llback is an est
1c220 69 6d 61 74 65 0a 2a 2a 20 20 20 20 20 20 20 20  imate.**        
1c230 20 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20    of the number 
1c240 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 20 6f  of nanoseconds o
1c250 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
1c260 65 20 72 65 71 75 69 72 65 64 20 74 6f 0a 2a 2a  e required to.**
1c270 20 20 20 20 20 20 20 20 20 20 72 75 6e 20 74 68            run th
1c280 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1c290 66 72 6f 6d 20 73 74 61 72 74 20 74 6f 20 66 69  from start to fi
1c2a0 6e 69 73 68 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nish..*/.SQLITE_
1c2b0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
1c2c0 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
1c2d0 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
1c2e0 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
1c2f0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
1c300 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45  d*);.SQLITE_EXPE
1c310 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
1c320 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
1c330 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
1c340 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
1c350 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
1c360 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
1c370 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1c380 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
1c390 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
1c3a0 20 7b 48 31 32 39 31 30 7d 20 3c 53 36 30 34 30   {H12910} <S6040
1c3b0 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
1c3c0 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73  utine configures
1c3d0 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
1c3e0 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72  tion - the.** pr
1c3f0 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
1c400 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  - that is invoke
1c410 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
1c420 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75  uring long.** ru
1c430 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b  nning calls to [
1c440 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
1c450 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1c460 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1c470 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20  3_get_table()]. 
1c480 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
1c490 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
1c4a0 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
1c4b0 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
1c4c0 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
1c4d0 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ery..**.** If th
1c4e0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
1c4f0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
1c500 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
1c510 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
1c520 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
1c530 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
1c540 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
1c550 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
1c560 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
1c570 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
1c580 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
1c590 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  ess handler must
1c5a0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
1c5b0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
1c5c0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
1c5d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1c5e0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
1c5f0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
1c600 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
1c610 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1c620 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1c630 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
1c640 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
1c650 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c660 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
1c670 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
1c680 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
1c690 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1c6a0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31  TS:.**.** {H1291
1c6b0 31 7d 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  1} The callback 
1c6c0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1c6d0 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
1c6e0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1c6f0 29 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  ).**          is
1c700 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
1c710 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
1c720 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
1c730 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b  to.**          [
1c740 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1c750 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 32 7d 20  .**.** {H12912} 
1c760 54 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  The progress cal
1c770 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1c780 20 6f 6e 63 65 20 66 6f 72 20 65 76 65 72 79 20   once for every 
1c790 4e 20 76 69 72 74 75 61 6c 0a 2a 2a 20 20 20 20  N virtual.**    
1c7a0 20 20 20 20 20 20 6d 61 63 68 69 6e 65 20 6f 70        machine op
1c7b0 63 6f 64 65 73 2c 20 77 68 65 72 65 20 4e 20 69  codes, where N i
1c7c0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
1c7d0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 20 20 20 20  ument to.**     
1c7e0 20 20 20 20 20 74 68 65 20 5b 73 71 6c 69 74 65       the [sqlite
1c7f0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1c800 65 72 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  er()] call that 
1c810 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20 20  registered.**   
1c820 20 20 20 20 20 20 20 74 68 65 20 63 61 6c 6c 62         the callb
1c830 61 63 6b 2e 20 20 49 66 20 4e 20 69 73 20 6c 65  ack.  If N is le
1c840 73 73 20 74 68 61 6e 20 31 2c 20 73 71 6c 69 74  ss than 1, sqlit
1c850 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1c860 6c 65 72 28 29 0a 2a 2a 20 20 20 20 20 20 20 20  ler().**        
1c870 20 20 61 63 74 73 20 61 73 20 69 66 20 61 20 4e    acts as if a N
1c880 55 4c 4c 20 70 72 6f 67 72 65 73 73 20 68 61 6e  ULL progress han
1c890 64 6c 65 72 20 68 61 64 20 62 65 65 6e 20 73 70  dler had been sp
1c8a0 65 63 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  ecified..**.** {
1c8b0 48 31 32 39 31 33 7d 20 54 68 65 20 70 72 6f 67  H12913} The prog
1c8c0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 69 74  ress callback it
1c8d0 73 65 6c 66 20 69 73 20 69 64 65 6e 74 69 66 69  self is identifi
1c8e0 65 64 20 62 79 20 74 68 65 20 74 68 69 72 64 0a  ed by the third.
1c8f0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 72 67 75  **          argu
1c900 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1c910 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1c920 28 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31  ()..**.** {H1291
1c930 34 7d 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  4} The fourth ar
1c940 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1c950 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1c960 65 72 28 29 20 69 73 20 61 0a 2a 2a 20 20 20 20  er() is a.**    
1c970 20 20 20 20 20 20 76 6f 69 64 20 70 6f 69 6e 74        void point
1c980 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
1c990 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
1c9a0 63 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  ck.**          f
1c9b0 75 6e 63 74 69 6f 6e 20 65 61 63 68 20 74 69 6d  unction each tim
1c9c0 65 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 2e  e it is invoked.
1c9d0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31 35 7d 20  .**.** {H12915} 
1c9e0 49 66 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  If a call to [sq
1c9f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
1ca00 73 75 6c 74 73 20 69 6e 20 66 65 77 65 72 20 74  sults in fewer t
1ca10 68 61 6e 20 4e 20 6f 70 63 6f 64 65 73 0a 2a 2a  han N opcodes.**
1ca20 20 20 20 20 20 20 20 20 20 20 62 65 69 6e 67 20            being 
1ca30 65 78 65 63 75 74 65 64 2c 20 74 68 65 6e 20 74  executed, then t
1ca40 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
1ca50 62 61 63 6b 20 69 73 20 6e 65 76 65 72 20 69 6e  back is never in
1ca60 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  voked..**.** {H1
1ca70 32 39 31 36 7d 20 45 76 65 72 79 20 63 61 6c 6c  2916} Every call
1ca80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f   to [sqlite3_pro
1ca90 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 29 5d  gress_handler()]
1caa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 76 65  .**          ove
1cab0 72 77 72 69 74 65 73 20 61 6e 79 20 70 72 65 76  rwrites any prev
1cac0 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72 65  iously registere
1cad0 64 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  d progress handl
1cae0 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 39 31  er..**.** {H1291
1caf0 37 7d 20 49 66 20 74 68 65 20 70 72 6f 67 72 65  7} If the progre
1cb00 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  ss handler callb
1cb10 61 63 6b 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ack is NULL then
1cb20 20 6e 6f 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20   no progress.** 
1cb30 20 20 20 20 20 20 20 20 20 68 61 6e 64 6c 65 72           handler
1cb40 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
1cb50 2a 2a 20 7b 48 31 32 39 31 38 7d 20 49 66 20 74  ** {H12918} If t
1cb60 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
1cb70 62 61 63 6b 20 72 65 74 75 72 6e 73 20 61 20 72  back returns a r
1cb80 65 73 75 6c 74 20 6f 74 68 65 72 20 74 68 61 6e  esult other than
1cb90 20 30 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20   0, then.**     
1cba0 20 20 20 20 20 74 68 65 20 62 65 68 61 76 69 6f       the behavio
1cbb0 72 20 69 73 20 61 20 69 66 20 5b 73 71 6c 69 74  r is a if [sqlit
1cbc0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 20  e3_interrupt()] 
1cbd0 68 61 64 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e  had been called.
1cbe0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 53 33  .**          <S3
1cbf0 30 35 30 30 3e 0a 2a 2f 0a 76 6f 69 64 20 73 71  0500>.*/.void sq
1cc00 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1cc10 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1cc20 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
1cc30 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
1cc40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
1cc50 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
1cc60 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
1cc70 7b 48 31 32 37 30 30 7d 20 3c 53 34 30 32 30 30  {H12700} <S40200
1cc80 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  >.**.** These ro
1cc90 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
1cca0 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
1ccb0 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69  ile whose name i
1ccc0 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a  s given by the.*
1ccd0 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
1cce0 65 6e 74 2e 20 54 68 65 20 66 69 6c 65 6e 61 6d  ent. The filenam
1ccf0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
1cd00 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
1cd10 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
1cd20 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1cd30 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
1cd40 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
1cd50 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
1cd60 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
1cd70 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 41  ite3_open16(). A
1cd80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1cd90 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
1cda0 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
1cdb0 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
1cdc0 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
1cdd0 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
1cde0 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
1cdf0 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
1ce00 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1ce10 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
1ce20 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
1ce30 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
1ce40 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
1ce50 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
1ce60 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
1ce70 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
1ce80 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
1ce90 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  . If the databas
1cea0 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64  e is opened (and
1ceb0 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63  /or created) suc
1cec0 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a  cessfully, then.
1ced0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ** [SQLITE_OK] i
1cee0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68  s returned.  Oth
1cef0 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
1cf00 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
1cf10 65 64 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  ed.  The.** [sql
1cf20 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f  ite3_errmsg()] o
1cf30 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r [sqlite3_errms
1cf40 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  g16()] routines 
1cf50 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
1cf60 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c  btain.** an Engl
1cf70 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73  ish language des
1cf80 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  cription of the 
1cf90 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  error..**.** The
1cfa0 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e   default encodin
1cfb0 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  g for the databa
1cfc0 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  se will be UTF-8
1cfd0 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   if.** sqlite3_o
1cfe0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
1cff0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 61  _open_v2() is ca
1d000 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d  lled and.** UTF-
1d010 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
1d020 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 73   byte order if s
1d030 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
1d040 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57  is used..**.** W
1d050 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
1d060 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
1d070 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
1d080 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
1d090 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
1d0a0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
1d0b0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
1d0c0 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
1d0d0 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
1d0e0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
1d0f0 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
1d100 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
1d110 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
1d120 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1d130 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
1d140 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
1d150 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
1d160 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
1d170 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
1d180 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
1d190 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
1d1a0 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
1d1b0 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
1d1c0 63 74 69 6f 6e 2e 20 20 54 68 65 20 66 6c 61 67  ction.  The flag
1d1d0 73 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  s parameter can 
1d1e0 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
1d1f0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
1d200 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
1d210 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
1d220 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
1d230 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
1d240 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ] or [SQLITE_OPE
1d250 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
1d260 67 73 3a 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  gs:.**.** <dl>.*
1d270 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  * <dt>[SQLITE_OP
1d280 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
1d290 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1d2a0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1d2b0 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
1d2c0 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
1d2d0 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
1d2e0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
1d2f0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
1d300 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
1d310 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
1d320 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
1d330 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
1d340 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
1d350 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
1d360 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
1d370 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
1d380 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
1d390 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
1d3a0 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
1d3b0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
1d3c0 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
1d3d0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
1d3e0 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
1d3f0 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
1d400 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1d410 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  d.</dd>.**.** <d
1d420 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
1d430 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
1d440 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
1d450 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1d460 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1d470 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
1d480 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
1d490 20 69 73 20 63 72 65 61 74 65 73 20 69 74 20 69   is creates it i
1d4a0 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74  f.** it does not
1d4b0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20   already exist. 
1d4c0 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61  This is the beha
1d4d0 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77  vior that is alw
1d4e0 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20  ays used for.** 
1d4f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1d500 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nd sqlite3_open1
1d510 36 28 29 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64  6().</dd>.** </d
1d520 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
1d530 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
1d540 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1d550 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
1d560 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
1d570 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
1d580 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63   or one of the c
1d590 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
1d5a0 6e 20 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64  n above combined
1d5b0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
1d5c0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1d5d0 58 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  X] or [SQLITE_OP
1d5e0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
1d5f0 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ags,.** then the
1d600 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
1d610 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
1d620 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1d630 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
1d640 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
1d650 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1d660 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
1d670 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
1d680 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1d690 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
1d6a0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
1d6b0 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
1d6c0 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
1d6d0 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
1d6e0 74 2d 74 69 6d 65 2e 20 20 49 66 20 74 68 65 0a  t-time.  If the.
1d6f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1d700 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
1d710 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
1d720 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d730 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
1d740 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
1d750 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
1d760 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
1d770 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
1d780 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
1d790 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
1d7a0 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
1d7b0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65  *.** If the file
1d7c0 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
1d7d0 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
1d7e0 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
1d7f0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
1d800 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
1d810 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
1d820 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  n.  This in-memo
1d830 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
1d840 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
1d850 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1d860 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
1d870 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
1d880 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
1d890 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
1d8a0 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
1d8b0 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
1d8c0 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
1d8d0 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
1d8e0 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
1d8f0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
1d900 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
1d910 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
1d920 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
1d930 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
1d940 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
1d950 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
1d960 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
1d970 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
1d980 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
1d990 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ity..**.** If th
1d9a0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
1d9b0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
1d9c0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1d9d0 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
1d9e0 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
1d9f0 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 54  l be created.  T
1da00 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
1da10 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
1da20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
1da30 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
1da40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1da50 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1da60 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ed..**.** The fo
1da70 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
1da80 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1da90 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
1daa0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
1dab0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
1dac0 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
1dad0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1dae0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
1daf0 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
1db00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
1db10 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20 74  hould use.  If t
1db20 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1db30 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
1db40 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
1db50 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1db60 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
1db70 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  s used..**.** <b
1db80 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
1db90 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
1dba0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
1dbb0 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
1dbc0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
1dbd0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1dbe0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
1dbf0 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
1dc00 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
1dc10 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
1dc20 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
1dc30 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
1dc40 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
1dc50 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
1dc60 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
1dc70 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
1dc80 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
1dc90 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
1dca0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1dcb0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1dcc0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
1dcd0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30  TS:.**.** {H1270
1dce0 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
1dcf0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
1dd00 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
1dd10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
1dd20 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1dd30 20 69 6e 74 65 72 66 61 63 65 73 20 63 72 65 61   interfaces crea
1dd40 74 65 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20  te a new.**     
1dd50 20 20 20 20 20 5b 64 61 74 61 62 61 73 65 20 63       [database c
1dd60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 73 6f 63  onnection] assoc
1dd70 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 20 20  iated with.**   
1dd80 20 20 20 20 20 20 20 74 68 65 20 64 61 74 61 62         the datab
1dd90 61 73 65 20 66 69 6c 65 20 67 69 76 65 6e 20 69  ase file given i
1dda0 6e 20 74 68 65 69 72 20 66 69 72 73 74 20 70 61  n their first pa
1ddb0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  rameter..**.** {
1ddc0 48 31 32 37 30 32 7d 20 54 68 65 20 66 69 6c 65  H12702} The file
1ddd0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
1dde0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1ddf0 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20 20 20 20  UTF-8.**        
1de00 20 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f    for [sqlite3_o
1de10 70 65 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  pen()] and [sqli
1de20 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 61  te3_open_v2()] a
1de30 6e 64 20 61 73 20 55 54 46 2d 31 36 0a 2a 2a 20  nd as UTF-16.** 
1de40 20 20 20 20 20 20 20 20 20 69 6e 20 74 68 65 20           in the 
1de50 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1de60 72 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  r for [sqlite3_o
1de70 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  pen16()]..**.** 
1de80 7b 48 31 32 37 30 33 7d 20 41 20 73 75 63 63 65  {H12703} A succe
1de90 73 73 66 75 6c 20 69 6e 76 6f 63 61 74 69 6f 6e  ssful invocation
1dea0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   of [sqlite3_ope
1deb0 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
1dec0 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 20 20 20  pen16()],.**    
1ded0 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74 65        or [sqlite
1dee0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 77 72 69  3_open_v2()] wri
1def0 74 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  tes a pointer to
1df00 20 61 20 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20   a new.**       
1df10 20 20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e     [database con
1df20 6e 65 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 2a 70  nection] into *p
1df30 70 44 62 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  pDb..**.** {H127
1df40 30 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  04} The [sqlite3
1df50 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
1df60 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
1df70 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  d.**          [s
1df80 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1df90 5d 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74  ] interfaces ret
1dfa0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
1dfb0 75 70 6f 6e 20 73 75 63 63 65 73 73 2c 0a 2a 2a  upon success,.**
1dfc0 20 20 20 20 20 20 20 20 20 20 6f 72 20 61 6e 20            or an 
1dfd0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
1dfe0 6f 72 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c  or code] on fail
1dff0 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ure..**.** {H127
1e000 30 36 7d 20 54 68 65 20 64 65 66 61 75 6c 74 20  06} The default 
1e010 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  text encoding fo
1e020 72 20 61 20 6e 65 77 20 64 61 74 61 62 61 73 65  r a new database
1e030 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
1e040 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
1e050 74 65 33 5f 6f 70 65 6e 28 29 5d 20 6f 72 20 5b  te3_open()] or [
1e060 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1e070 29 5d 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38  )] will be UTF-8
1e080 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 30 37 7d  ..**.** {H12707}
1e090 20 54 68 65 20 64 65 66 61 75 6c 74 20 74 65 78   The default tex
1e0a0 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 61  t encoding for a
1e0b0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 72   new database cr
1e0c0 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20  eated using.**  
1e0d0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
1e0e0 5f 6f 70 65 6e 31 36 28 29 5d 20 77 69 6c 6c 20  _open16()] will 
1e0f0 62 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  be UTF-16..**.**
1e100 20 7b 48 31 32 37 30 39 7d 20 54 68 65 20 5b 73   {H12709} The [s
1e110 71 6c 69 74 65 33 5f 6f 70 65 6e 28 46 2c 44 29  qlite3_open(F,D)
1e120 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 65  ] interface is e
1e130 71 75 69 76 61 6c 65 6e 74 20 74 6f 0a 2a 2a 20  quivalent to.** 
1e140 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
1e150 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c  3_open_v2(F,D,G,
1e160 30 29 5d 20 77 68 65 72 65 20 74 68 65 20 47 20  0)] where the G 
1e170 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
1e180 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
1e190 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1e1a0 7c 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  |[SQLITE_OPEN_CR
1e1b0 45 41 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  EATE]..**.** {H1
1e1c0 32 37 31 31 7d 20 49 66 20 74 68 65 20 47 20 70  2711} If the G p
1e1d0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
1e1e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
1e1f0 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69 6e 73 20  ,G,V)] contains 
1e200 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
1e210 62 69 74 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  bit value [SQLIT
1e220 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
1e230 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1e240 73 65 20 69 73 20 6f 70 65 6e 65 64 0a 2a 2a 20  se is opened.** 
1e250 20 20 20 20 20 20 20 20 20 66 6f 72 20 72 65 61           for rea
1e260 64 69 6e 67 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  ding only..**.**
1e270 20 7b 48 31 32 37 31 32 7d 20 49 66 20 74 68 65   {H12712} If the
1e280 20 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   G parameter to 
1e290 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1e2a0 28 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61  (F,D,G,V)] conta
1e2b0 69 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ins the.**      
1e2c0 20 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53      bit value [S
1e2d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1e2e0 52 49 54 45 5d 20 74 68 65 6e 20 74 68 65 20 64  RITE] then the d
1e2f0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1e300 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
1e310 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1e320 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
1e330 72 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e  r for reading on
1e340 6c 79 20 69 66 20 74 68 65 0a 2a 2a 20 20 20 20  ly if the.**    
1e350 20 20 20 20 20 20 66 69 6c 65 20 69 73 20 77 72        file is wr
1e360 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
1e370 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1e380 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ystem..**.** {H1
1e390 32 37 31 33 7d 20 49 66 20 74 68 65 20 47 20 70  2713} If the G p
1e3a0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
1e3b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44  ite3_open_v2(F,D
1e3c0 2c 47 2c 56 29 5d 20 6f 6d 69 74 73 20 74 68 65  ,G,V)] omits the
1e3d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 62 69 74  .**          bit
1e3e0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 4f   value [SQLITE_O
1e3f0 50 45 4e 5f 43 52 45 41 54 45 5d 20 61 6e 64 20  PEN_CREATE] and 
1e400 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
1e410 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20  s not.**        
1e420 20 20 70 72 65 76 69 6f 75 73 6c 79 20 65 78 69    previously exi
1e430 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
1e440 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1e450 7b 48 31 32 37 31 34 7d 20 49 66 20 74 68 65 20  {H12714} If the 
1e460 47 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  G parameter to [
1e470 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1e480 46 2c 44 2c 47 2c 56 29 5d 20 63 6f 6e 74 61 69  F,D,G,V)] contai
1e490 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
1e4a0 20 20 20 62 69 74 20 76 61 6c 75 65 20 5b 53 51     bit value [SQ
1e4b0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
1e4c0 5d 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  ] and the databa
1e4d0 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20  se does not.**  
1e4e0 20 20 20 20 20 20 20 20 70 72 65 76 69 6f 75 73          previous
1e4f0 6c 79 20 65 78 69 73 74 2c 20 74 68 65 6e 20 61  ly exist, then a
1e500 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
1e510 65 20 74 6f 20 63 72 65 61 74 65 20 61 6e 64 0a  e to create and.
1e520 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 69 74  **          init
1e530 69 61 6c 69 7a 65 20 74 68 65 20 64 61 74 61 62  ialize the datab
1e540 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ase..**.** {H127
1e550 31 37 7d 20 49 66 20 74 68 65 20 66 69 6c 65 6e  17} If the filen
1e560 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ame argument to 
1e570 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
1e580 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
1e590 36 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  6()],.**        
1e5a0 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70    or [sqlite3_op
1e5b0 65 6e 5f 76 32 28 29 5d 20 69 73 20 22 3a 6d 65  en_v2()] is ":me
1e5c0 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 6e 20  mory:", then an 
1e5d0 70 72 69 76 61 74 65 2c 0a 2a 2a 20 20 20 20 20  private,.**     
1e5e0 20 20 20 20 20 65 70 68 65 6d 65 72 61 6c 2c 20       ephemeral, 
1e5f0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
1e600 73 65 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  se is created fo
1e610 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
1e620 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 3c 74  ..**          <t
1e630 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45 5f 4f 50  odo>Is SQLITE_OP
1e640 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c 49 54 45  EN_CREATE|SQLITE
1e650 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
1e660 72 65 71 75 69 72 65 64 0a 2a 2a 20 20 20 20 20  required.**     
1e670 20 20 20 20 20 69 6e 20 73 71 6c 69 74 65 33 5f       in sqlite3_
1e680 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74 6f 64 6f  open_v2()?</todo
1e690 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37 31 39 7d  >.**.** {H12719}
1e6a0 20 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   If the filename
1e6b0 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65   is NULL or an e
1e6c0 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
1e6d0 6e 20 61 20 70 72 69 76 61 74 65 2c 0a 2a 2a 20  n a private,.** 
1e6e0 20 20 20 20 20 20 20 20 20 65 70 68 65 6d 65 72           ephemer
1e6f0 61 6c 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  al on-disk datab
1e700 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
1e710 74 65 64 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ted..**         
1e720 20 3c 74 6f 64 6f 3e 49 73 20 53 51 4c 49 54 45   <todo>Is SQLITE
1e730 5f 4f 50 45 4e 5f 43 52 45 41 54 45 7c 53 51 4c  _OPEN_CREATE|SQL
1e740 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1e750 54 45 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 20  TE required.**  
1e760 20 20 20 20 20 20 20 20 69 6e 20 73 71 6c 69 74          in sqlit
1e770 65 33 5f 6f 70 65 6e 5f 76 32 28 29 3f 3c 2f 74  e3_open_v2()?</t
1e780 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  odo>.**.** {H127
1e790 32 31 7d 20 54 68 65 20 5b 64 61 74 61 62 61 73  21} The [databas
1e7a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 72  e connection] cr
1e7b0 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eated by [sqlite
1e7c0 33 5f 6f 70 65 6e 5f 76 32 28 46 2c 44 2c 47 2c  3_open_v2(F,D,G,
1e7d0 56 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  V)].**          
1e7e0 77 69 6c 6c 20 75 73 65 20 74 68 65 20 5b 73 71  will use the [sq
1e7f0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1e800 74 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  t identified by 
1e810 74 68 65 20 56 20 70 61 72 61 6d 65 74 65 72 2c  the V parameter,
1e820 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
1e830 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1e840 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1e850 20 69 66 20 56 20 69 73 20 61 20 4e 55 4c 4c 20   if V is a NULL 
1e860 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  pointer..**.** {
1e870 48 31 32 37 32 33 7d 20 54 77 6f 20 5b 64 61 74  H12723} Two [dat
1e880 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e890 73 5d 20 77 69 6c 6c 20 73 68 61 72 65 20 61 20  s] will share a 
1e8a0 63 6f 6d 6d 6f 6e 20 63 61 63 68 65 20 69 66 20  common cache if 
1e8b0 62 6f 74 68 20 77 65 72 65 0a 2a 2a 20 20 20 20  both were.**    
1e8c0 20 20 20 20 20 20 6f 70 65 6e 65 64 20 77 69 74        opened wit
1e8d0 68 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 77  h the same VFS w
1e8e0 68 69 6c 65 20 5b 73 68 61 72 65 64 20 63 61 63  hile [shared cac
1e8f0 68 65 20 6d 6f 64 65 5d 20 77 61 73 20 65 6e 61  he mode] was ena
1e900 62 6c 65 64 20 61 6e 64 0a 2a 2a 20 20 20 20 20  bled and.**     
1e910 20 20 20 20 20 69 66 20 62 6f 74 68 20 66 69 6c       if both fil
1e920 65 6e 61 6d 65 73 20 63 6f 6d 70 61 72 65 20 65  enames compare e
1e930 71 75 61 6c 20 75 73 69 6e 67 20 6d 65 6d 63 6d  qual using memcm
1e940 70 28 29 20 61 66 74 65 72 20 68 61 76 69 6e 67  p() after having
1e950 20 62 65 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20   been.**        
1e960 20 20 70 72 6f 63 65 73 73 65 64 20 62 79 20 74    processed by t
1e970 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  he [sqlite3_vfs 
1e980 7c 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 5d  | xFullPathname]
1e990 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 56   method of the V
1e9a0 46 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  FS..*/.int sqlit
1e9b0 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
1e9c0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
1e9d0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
1e9e0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
1e9f0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
1ea00 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
1ea10 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
1ea20 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
1ea30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
1ea40 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
1ea50 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
1ea60 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
1ea70 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
1ea80 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
1ea90 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
1eaa0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
1eab0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1eac0 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
1ead0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
1eae0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
1eaf0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
1eb00 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
1eb10 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
1eb20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
1eb30 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
1eb40 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
1eb50 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
1eb60 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
1eb70 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
1eb80 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
1eb90 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
1eba0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
1ebb0 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
1ebc0 73 61 67 65 73 20 7b 48 31 32 38 30 30 7d 20 3c  sages {H12800} <
1ebd0 53 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S60200>.**.** Th
1ebe0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
1ebf0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
1ec00 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
1ec10 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
1ec20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
1ec30 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
1ec40 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1ec50 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
1ec60 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
1ec70 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
1ec80 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1ec90 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
1eca0 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
1ecb0 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
1ecc0 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
1ecd0 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
1ece0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
1ecf0 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
1ed00 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
1ed10 69 6e 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74  ined.  The sqlit
1ed20 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
1ed30 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ode().** interfa
1ed40 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65  ce is the same e
1ed50 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
1ed60 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
1ed70 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72   .** [extended r
1ed80 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e  esult code] even
1ed90 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72   when extended r
1eda0 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a  esult codes are.
1edb0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  ** disabled..**.
1edc0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
1edd0 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
1ede0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
1edf0 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
1ee00 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
1ee10 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
1ee20 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
1ee30 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1ee40 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
1ee50 0a 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** Memory to ho
1ee60 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
1ee70 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
1ee80 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
1ee90 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
1eea0 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
1eeb0 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
1eec0 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
1eed0 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
1eee0 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
1eef0 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
1ef00 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
1ef10 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
1ef20 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
1ef30 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
1ef40 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
1ef50 6e 73 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ns..**.** When t
1ef60 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
1ef70 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
1ef80 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
1ef90 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
1efa0 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
1efb0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
1efc0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1efd0 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
1efe0 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
1eff0 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
1f000 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
1f010 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
1f020 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
1f030 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
1f040 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
1f050 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
1f060 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
1f070 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
1f080 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
1f090 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
1f0a0 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
1f0b0 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
1f0c0 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
1f0d0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1f0e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
1f0f0 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
1f100 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
1f110 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
1f120 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
1f130 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
1f140 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
1f150 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
1f160 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
1f170 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
1f180 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
1f190 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
1f1a0 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
1f1b0 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
1f1c0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
1f1d0 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
1f1e0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
1f1f0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
1f200 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
1f210 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
1f220 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
1f230 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
1f240 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
1f250 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
1f260 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
1f270 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  not be set..**.*
1f280 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a  * INVARIANTS:.**
1f290 0a 2a 2a 20 7b 48 31 32 38 30 31 7d 20 54 68 65  .** {H12801} The
1f2a0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1f2b0 65 28 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20  e(D)] interface 
1f2c0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
1f2d0 72 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ric.**          
1f2e0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
1f2f0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
1f300 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
1f310 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 0a 2a 2a  most recently.**
1f320 20 20 20 20 20 20 20 20 20 20 66 61 69 6c 65 64            failed
1f330 20 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 20   interface call 
1f340 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1f350 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
1f360 6e 6e 65 63 74 69 6f 6e 5d 20 44 2e 0a 2a 2a 0a  nnection] D..**.
1f370 2a 2a 20 7b 48 31 32 38 30 32 7d 20 54 68 65 20  ** {H12802} The 
1f380 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
1f390 64 5f 65 72 72 63 6f 64 65 28 44 29 5d 20 69 6e  d_errcode(D)] in
1f3a0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1f3b0 74 68 65 20 6e 75 6d 65 72 69 63 0a 2a 2a 20 20  the numeric.**  
1f3c0 20 20 20 20 20 20 20 20 5b 65 78 74 65 6e 64 65          [extende
1f3d0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
1f3e0 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
1f3f0 6e 74 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ntly.**         
1f400 20 66 61 69 6c 65 64 20 69 6e 74 65 72 66 61 63   failed interfac
1f410 65 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  e call associate
1f420 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
1f430 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1f440 20 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30   D..**.** {H1280
1f450 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
1f460 65 72 72 6d 73 67 28 44 29 5d 20 61 6e 64 20 5b  errmsg(D)] and [
1f470 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1f480 28 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  (D)].**         
1f490 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 74 75   interfaces retu
1f4a0 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
1f4b0 61 67 65 20 74 65 78 74 20 74 68 61 74 20 64 65  age text that de
1f4c0 73 63 72 69 62 65 73 0a 2a 2a 20 20 20 20 20 20  scribes.**      
1f4d0 20 20 20 20 74 68 65 20 65 72 72 6f 72 20 69 6e      the error in
1f4e0 20 74 68 65 20 6d 6f 73 74 6c 79 20 72 65 63 65   the mostly rece
1f4f0 6e 74 6c 79 20 66 61 69 6c 65 64 20 69 6e 74 65  ntly failed inte
1f500 72 66 61 63 65 20 63 61 6c 6c 2c 0a 2a 2a 20 20  rface call,.**  
1f510 20 20 20 20 20 20 20 20 65 6e 63 6f 64 65 64 20          encoded 
1f520 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
1f530 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63  or UTF-16 respec
1f540 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48  tively..**.** {H
1f550 31 32 38 30 37 7d 20 54 68 65 20 73 74 72 69 6e  12807} The strin
1f560 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  gs returned by [
1f570 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1f580 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  ] and [sqlite3_e
1f590 72 72 6d 73 67 31 36 28 29 5d 0a 2a 2a 20 20 20  rrmsg16()].**   
1f5a0 20 20 20 20 20 20 20 61 72 65 20 76 61 6c 69 64         are valid
1f5b0 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
1f5c0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
1f5d0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   call..**.** {H1
1f5e0 32 38 30 38 7d 20 43 61 6c 6c 73 20 74 6f 20 41  2808} Calls to A
1f5f0 50 49 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  PI routines that
1f600 20 64 6f 20 6e 6f 74 20 72 65 74 75 72 6e 20 61   do not return a
1f610 6e 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  n error code.** 
1f620 20 20 20 20 20 20 20 20 20 28 65 78 61 6d 70 6c           (exampl
1f630 65 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  e: [sqlite3_data
1f640 5f 63 6f 75 6e 74 28 29 5d 29 20 64 6f 20 6e 6f  _count()]) do no
1f650 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 68  t.**          ch
1f660 61 6e 67 65 20 74 68 65 20 65 72 72 6f 72 20 63  ange the error c
1f670 6f 64 65 20 6f 72 20 6d 65 73 73 61 67 65 20 72  ode or message r
1f680 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20  eturned by.**   
1f690 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
1f6a0 65 72 72 63 6f 64 65 28 29 5d 2c 20 5b 73 71 6c  errcode()], [sql
1f6b0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
1f6c0 72 63 6f 64 65 28 29 5d 2c 0a 2a 2a 20 20 20 20  rcode()],.**    
1f6d0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
1f6e0 72 72 6d 73 67 28 29 5d 2c 20 6f 72 20 5b 73 71  rrmsg()], or [sq
1f6f0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1f700 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 38 30 39  ]..**.** {H12809
1f710 7d 20 49 6e 74 65 72 66 61 63 65 73 20 74 68 61  } Interfaces tha
1f720 74 20 61 72 65 20 6e 6f 74 20 61 73 73 6f 63 69  t are not associ
1f730 61 74 65 64 20 77 69 74 68 20 61 20 73 70 65 63  ated with a spec
1f740 69 66 69 63 0a 2a 2a 20 20 20 20 20 20 20 20 20  ific.**         
1f750 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1f760 63 74 69 6f 6e 5d 20 28 65 78 61 6d 70 6c 65 73  ction] (examples
1f770 3a 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  :.**          [s
1f780 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
1f790 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 6e  ] or [sqlite3_en
1f7a0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
1f7b0 65 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  e()].**         
1f7c0 20 64 6f 20 6e 6f 74 20 63 68 61 6e 67 65 20 74   do not change t
1f7d0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1f7e0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
1f7f0 20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f    [sqlite3_errco
1f800 64 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  de()], [sqlite3_
1f810 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
1f820 28 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  ()],.**         
1f830 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1f840 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
1f850 5f 65 72 72 6d 73 67 31 36 28 29 5d 2e 0a 2a 2f  _errmsg16()]..*/
1f860 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72  .int sqlite3_err
1f870 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
1f880 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  );.int sqlite3_e
1f890 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
1f8a0 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f  sqlite3 *db);.co
1f8b0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1f8c0 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33  3_errmsg(sqlite3
1f8d0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
1f8e0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
1f8f0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1f900 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
1f910 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
1f920 74 20 7b 48 31 33 30 30 30 7d 20 3c 48 31 33 30  t {H13000} <H130
1f930 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  10>.** KEYWORDS:
1f940 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
1f950 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
1f960 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
1f970 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
1f980 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
1f990 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
1f9a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
1f9b0 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
1f9c0 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
1f9d0 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
1f9e0 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
1f9f0 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
1fa00 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
1fa10 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
1fa20 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
1fa30 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
1fa40 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
1fa50 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
1fa60 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
1fa70 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
1fa80 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
1fa90 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1faa0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
1fab0 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
1fac0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
1fad0 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
1fae0 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
1faf0 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
1fb00 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
1fb10 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
1fb20 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
1fb30 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
1fb40 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1fb50 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
1fb60 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
1fb70 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
1fb80 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
1fb90 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
1fba0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
1fbb0 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
1fbc0 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
1fbd0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
1fbe0 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
1fbf0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1fc00 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
1fc10 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
1fc20 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
1fc30 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
1fc40 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
1fc50 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1fc60 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
1fc70 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
1fc80 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
1fc90 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
1fca0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
1fcb0 69 6d 65 20 4c 69 6d 69 74 73 20 7b 48 31 32 37  ime Limits {H127
1fcc0 36 30 7d 20 3c 53 32 30 36 30 30 3e 0a 2a 2a 0a  60} <S20600>.**.
1fcd0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1fce0 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
1fcf0 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
1fd00 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
1fd10 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
1fd20 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
1fd30 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
1fd40 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1fd50 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
1fd60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1fd70 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
1fd80 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
1fd90 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
1fda0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1fdb0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
1fdc0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
1fdd0 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
1fde0 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
1fdf0 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
1fe00 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
1fe10 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
1fe20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
1fe30 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
1fe40 73 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e  struct.  The fun
1fe50 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1fe60 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 0a 2a 2a 0a  e old limit..**.
1fe70 2a 2a 20 49 66 20 74 68 65 20 6e 65 77 20 6c 69  ** If the new li
1fe80 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
1fe90 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
1fea0 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
1feb0 2e 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6c 69 6d  ..** For the lim
1fec0 69 74 20 63 61 74 65 67 6f 72 79 20 6f 66 20 53  it category of S
1fed0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 58 59 5a 20  QLITE_LIMIT_XYZ 
1fee0 74 68 65 72 65 20 69 73 20 61 20 68 61 72 64 20  there is a hard 
1fef0 75 70 70 65 72 0a 2a 2a 20 62 6f 75 6e 64 20 73  upper.** bound s
1ff00 65 74 20 62 79 20 61 20 63 6f 6d 70 69 6c 65 2d  et by a compile-
1ff10 74 69 6d 65 20 43 20 70 72 65 70 72 6f 63 65 73  time C preproces
1ff20 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d 65 64 20  sor macro named 
1ff30 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 2e 0a  SQLITE_MAX_XYZ..
1ff40 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
1ff50 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
1ff60 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
1ff70 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d 70 74  X_".).** Attempt
1ff80 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
1ff90 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
1ffa0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
1ffb0 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
1ffc0 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
1ffd0 65 20 68 61 72 64 20 75 70 70 65 72 20 6c 69 6d  e hard upper lim
1ffe0 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20 74 69  it..**.** Run ti
1fff0 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
20000 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
20010 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
20020 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
20030 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
20040 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
20050 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
20060 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
20070 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
20080 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
20090 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
200a0 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
200b0 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
200c0 62 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61  bbrowser that ha
200d0 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
200e0 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
200f0 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
20100 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
20110 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
20120 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
20130 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
20140 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
20150 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
20160 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
20170 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
20180 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
20190 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
201a0 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
201b0 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
201c0 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
201d0 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
201e0 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
201f0 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
20200 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
20210 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
20220 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
20230 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
20240 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
20250 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
20260 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
20270 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
20280 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
20290 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
202a0 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
202b0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
202c0 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
202d0 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
202e0 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
202f0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
20300 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
20310 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
20320 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
20330 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
20340 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  es..**.** INVARI
20350 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  ANTS:.**.** {H12
20360 37 36 32 7d 20 41 20 73 75 63 63 65 73 73 66 75  762} A successfu
20370 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
20380 65 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d  e3_limit(D,C,V)]
20390 20 77 68 65 72 65 20 56 20 69 73 0a 2a 2a 20 20   where V is.**  
203a0 20 20 20 20 20 20 20 20 70 6f 73 69 74 69 76 65          positive
203b0 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 69 6d   changes the lim
203c0 69 74 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f  it on the size o
203d0 66 20 63 6f 6e 73 74 72 75 63 74 20 43 20 69 6e  f construct C in
203e0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
203f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
20400 63 74 69 6f 6e 5d 20 44 20 74 6f 20 74 68 65 20  ction] D to the 
20410 6c 65 73 73 65 72 20 6f 66 20 56 20 61 6e 64 20  lesser of V and 
20420 74 68 65 20 68 61 72 64 20 75 70 70 65 72 0a 2a  the hard upper.*
20430 2a 20 20 20 20 20 20 20 20 20 20 62 6f 75 6e 64  *          bound
20440 20 6f 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20   on the size of 
20450 43 20 74 68 61 74 20 69 73 20 73 65 74 20 61 74  C that is set at
20460 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 0a 2a   compile-time..*
20470 2a 0a 2a 2a 20 7b 48 31 32 37 36 36 7d 20 41 20  *.** {H12766} A 
20480 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
20490 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  to [sqlite3_limi
204a0 74 28 44 2c 43 2c 56 29 5d 20 77 68 65 72 65 20  t(D,C,V)] where 
204b0 56 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a  V is negative.**
204c0 20 20 20 20 20 20 20 20 20 20 6c 65 61 76 65 73            leaves
204d0 20 74 68 65 20 73 74 61 74 65 20 6f 66 20 74 68   the state of th
204e0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
204f0 65 63 74 69 6f 6e 5d 20 44 20 75 6e 63 68 61 6e  ection] D unchan
20500 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 37  ged..**.** {H127
20510 36 39 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c  69} A successful
20520 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
20530 33 5f 6c 69 6d 69 74 28 44 2c 43 2c 56 29 5d 20  3_limit(D,C,V)] 
20540 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 20  returns the.**  
20550 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 6f 66          value of
20560 20 74 68 65 20 6c 69 6d 69 74 20 6f 6e 20 74 68   the limit on th
20570 65 20 73 69 7a 65 20 6f 66 20 63 6f 6e 73 74 72  e size of constr
20580 75 63 74 20 43 20 69 6e 20 74 68 65 0a 2a 2a 20  uct C in the.** 
20590 20 20 20 20 20 20 20 20 20 5b 64 61 74 61 62 61           [databa
205a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
205b0 20 61 73 20 69 74 20 77 61 73 20 70 72 69 6f 72   as it was prior
205c0 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 0a 2a 2f   to the call..*/
205d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d  .int sqlite3_lim
205e0 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  it(sqlite3*, int
205f0 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29   id, int newVal)
20600 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20610 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69  F: Run-Time Limi
20620 74 20 43 61 74 65 67 6f 72 69 65 73 20 7b 48 31  t Categories {H1
20630 32 37 39 30 7d 20 3c 48 31 32 37 36 30 3e 0a 2a  2790} <H12760>.*
20640 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
20650 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 6c 69  it category} {li
20660 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a  mit categories}.
20670 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
20680 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
20690 69 6f 75 73 20 61 73 70 65 63 74 73 20 6f 66 20  ious aspects of 
206a0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
206b0 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20  ection].** that 
206c0 63 61 6e 20 62 65 20 6c 69 6d 69 74 65 64 20 69  can be limited i
206d0 6e 20 73 69 7a 65 20 62 79 20 63 61 6c 6c 73 20  n size by calls 
206e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  to [sqlite3_limi
206f0 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 6d 65 61  t()]..** The mea
20700 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
20710 69 6f 75 73 20 6c 69 6d 69 74 73 20 61 72 65 20  ious limits are 
20720 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
20730 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
20740 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
20750 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
20760 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
20770 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
20780 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
20790 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  w.<dd>.**.** <dt
207a0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  >SQLITE_LIMIT_SQ
207b0 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  L_LENGTH</dt>.**
207c0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
207d0 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51   length of an SQ
207e0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  L statement.</dd
207f0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
20800 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
20810 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
20820 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
20830 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
20840 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
20850 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
20860 75 6c 74 20 73 65 74 20 6f 66 20 61 20 53 45 4c  ult set of a SEL
20870 45 43 54 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  ECT or the maxim
20880 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
20890 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
208a0 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
208b0 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
208c0 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 0a 2a  Y clause.</dd>.*
208d0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
208e0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
208f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
20900 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
20910 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
20920 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
20930 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
20940 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
20950 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
20960 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
20970 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
20980 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
20990 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
209a0 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  tement.</dd>.**.
209b0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
209c0 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
209d0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
209e0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
209f0 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
20a00 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
20a10 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
20a20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
20a30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  SQL statement.</
20a40 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
20a50 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
20a60 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
20a70 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
20a80 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
20a90 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
20aa0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
20ab0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
20ac0 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
20ad0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
20ae0 6e 75 6d 62 65 72 20 6f 66 20 61 74 74 61 63 68  number of attach
20af0 65 64 20 64 61 74 61 62 61 73 65 73 2e 3c 2f 64  ed databases.</d
20b00 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
20b10 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
20b20 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
20b30 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
20b40 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
20b50 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
20b60 6d 65 6e 74 20 74 6f 20 74 68 65 20 4c 49 4b 45  ment to the LIKE
20b70 20 6f 72 0a 2a 2a 20 47 4c 4f 42 20 6f 70 65 72   or.** GLOB oper
20b80 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ators.</dd>.**.*
20b90 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
20ba0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
20bb0 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
20bc0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
20bd0 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20 69  r of variables i
20be0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
20bf0 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20 62  nt that can.** b
20c00 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a 2a  e bound.</dd>.**
20c10 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
20c20 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
20c30 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
20c40 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
20c50 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
20c60 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
20c70 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
20c80 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
20c90 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
20ca0 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
20cb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
20cc0 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
20cd0 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
20ce0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
20cf0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
20d00 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
20d10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
20d20 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
20d30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
20d40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
20d50 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
20d60 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
20d70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20d80 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
20d90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20da0 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
20db0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
20dc0 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
20dd0 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
20de0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
20df0 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
20e00 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    9../*.** CAPI3
20e10 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
20e20 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
20e30 7b 48 31 33 30 31 30 7d 20 3c 53 31 30 30 30 30  {H13010} <S10000
20e40 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
20e50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
20e60 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f  mpiler}.**.** To
20e70 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
20e80 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
20e90 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
20ea0 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
20eb0 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
20ec0 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
20ed0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
20ee0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
20ef0 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
20f00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20f10 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
20f20 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 63 61  om a.** prior ca
20f30 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
20f40 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
20f50 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 20 5b  _open_v2()] or [
20f60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
20f70 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  ]..**.** The sec
20f80 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
20f90 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
20fa0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
20fb0 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
20fc0 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
20fd0 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
20fe0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
20ff0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
21000 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
21010 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
21020 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
21030 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
21040 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
21050 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
21060 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66  UTF-16..**.** If
21070 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
21080 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ent is less than
21090 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c   zero, then zSql
210a0 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
210b0 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
210c0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 49 66 20   terminator. If 
210d0 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
210e0 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  ative, then it i
210f0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
21100 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65   number of  byte
21110 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
21120 2e 20 20 57 68 65 6e 20 6e 42 79 74 65 20 69 73  .  When nByte is
21130 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
21140 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
21150 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
21160 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
21170 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
21180 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
21190 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
211a0 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
211b0 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
211c0 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
211d0 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
211e0 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
211f0 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
21200 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
21210 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
21220 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
21230 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
21240 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
21250 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
21260 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
21270 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
21280 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
21290 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
212a0 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
212b0 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a  minator bytes..*
212c0 2a 0a 2a 2a 20 2a 70 7a 54 61 69 6c 20 69 73 20  *.** *pzTail is 
212d0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
212e0 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 20   the first byte 
212f0 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
21300 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 53 51 4c  the.** first SQL
21310 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
21320 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
21330 6e 65 73 20 6f 6e 6c 79 20 63 6f 6d 70 69 6c 65  nes only compile
21340 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 73 74   the first.** st
21350 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
21360 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
21370 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
21380 77 68 61 74 20 72 65 6d 61 69 6e 73 0a 2a 2a 20  what remains.** 
21390 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
213a0 2a 20 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66  * *ppStmt is lef
213b0 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
213c0 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
213d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
213e0 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
213f0 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
21400 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 49  ite3_step()].  I
21410 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
21420 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
21430 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
21440 20 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65   If the input te
21450 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
21460 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
21470 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
21480 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
21490 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
214a0 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
214b0 2e 0a 2a 2a 20 7b 41 31 33 30 31 38 7d 20 54 68  ..** {A13018} Th
214c0 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
214d0 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
214e0 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
214f0 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
21500 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
21510 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
21520 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
21530 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
21540 69 74 68 20 69 74 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  ith it..**.** On
21550 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54   success, [SQLIT
21560 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
21570 64 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  d, otherwise an 
21580 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
21590 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
215a0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
215b0 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
215c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
215d0 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
215e0 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
215f0 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
21600 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
21610 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
21620 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
21630 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
21640 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
21650 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
21660 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49  iscouraged..** I
21670 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
21680 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
21690 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
216a0 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
216b0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
216c0 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
216d0 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
216e0 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
216f0 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
21700 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
21710 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
21720 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
21730 76 65 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79  ve a differently
21740 20 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a   in two ways:.**
21750 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
21760 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
21770 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
21780 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
21790 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
217a0 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
217b0 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
217c0 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
217d0 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
217e0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
217f0 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
21800 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
21810 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
21820 20 20 49 66 20 74 68 65 20 73 63 68 65 6d 61 20    If the schema 
21830 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a  has changed in.*
21840 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b  * a way that mak
21850 65 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  es the statement
21860 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64   no longer valid
21870 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
21880 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a  )] will still.**
21890 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
218a0 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e  SCHEMA].  But un
218b0 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20  like the legacy 
218c0 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54  behavior, [SQLIT
218d0 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20  E_SCHEMA] is.** 
218e0 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f  now a fatal erro
218f0 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  r.  Calling [sql
21900 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21910 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f  )] again will no
21920 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72  t make the.** er
21930 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f  ror go away.  No
21940 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33  te: use [sqlite3
21950 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69  _errmsg()] to fi
21960 6e 64 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f  nd the text.** o
21970 66 20 74 68 65 20 70 61 72 73 69 6e 67 20 65 72  f the parsing er
21980 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74 73  ror that results
21990 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53   in an [SQLITE_S
219a0 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a  CHEMA] return..*
219b0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
219c0 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72  i>.** When an er
219d0 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
219e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
219f0 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
21a00 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
21a10 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
21a20 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
21a30 20 63 6f 64 65 73 5d 2e 20 20 54 68 65 20 6c 65   codes].  The le
21a40 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
21a50 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  s that.** [sqlit
21a60 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
21a70 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
21a80 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45  eneric [SQLITE_E
21a90 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
21aa0 65 0a 2a 2a 20 61 6e 64 20 79 6f 75 20 77 6f 75  e.** and you wou
21ab0 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
21ac0 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
21ad0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
21ae0 29 5d 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  )] in order.** t
21af0 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
21b00 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
21b10 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68  he problem. With
21b20 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
21b30 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c  e.** interfaces,
21b40 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
21b50 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
21b60 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
21b70 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
21b80 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
21b90 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
21ba0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 31 7d  :.**.** {H13011}
21bb0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   The [sqlite3_pr
21bc0 65 70 61 72 65 28 64 62 2c 7a 53 71 6c 2c 2e 2e  epare(db,zSql,..
21bd0 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  .)] and.**      
21be0 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65      [sqlite3_pre
21bf0 70 61 72 65 5f 76 32 28 64 62 2c 7a 53 71 6c 2c  pare_v2(db,zSql,
21c00 2e 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 73  ...)] interfaces
21c10 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a   interpret the.*
21c20 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20  *          text 
21c30 69 6e 20 74 68 65 69 72 20 7a 53 71 6c 20 70 61  in their zSql pa
21c40 72 61 6d 65 74 65 72 20 61 73 20 55 54 46 2d 38  rameter as UTF-8
21c50 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 32 7d  ..**.** {H13012}
21c60 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   The [sqlite3_pr
21c70 65 70 61 72 65 31 36 28 64 62 2c 7a 53 71 6c 2c  epare16(db,zSql,
21c80 2e 2e 2e 29 5d 20 61 6e 64 0a 2a 2a 20 20 20 20  ...)] and.**    
21c90 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70        [sqlite3_p
21ca0 72 65 70 61 72 65 31 36 5f 76 32 28 64 62 2c 7a  repare16_v2(db,z
21cb0 53 71 6c 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  Sql,...)] interf
21cc0 61 63 65 73 20 69 6e 74 65 72 70 72 65 74 20 74  aces interpret t
21cd0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  he.**          t
21ce0 65 78 74 20 69 6e 20 74 68 65 69 72 20 7a 53 71  ext in their zSq
21cf0 6c 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 55  l parameter as U
21d00 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
21d10 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
21d20 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 33 7d 20 49  **.** {H13013} I
21d30 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
21d40 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
21d50 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c 7a  _prepare_v2(db,z
21d60 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e 2e 29 5d 0a  Sql,nByte,...)].
21d70 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20  **          and 
21d80 69 74 73 20 76 61 72 69 61 6e 74 73 20 69 73 20  its variants is 
21d90 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20  less than zero, 
21da0 74 68 65 20 53 51 4c 20 74 65 78 74 20 69 73 0a  the SQL text is.
21db0 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 61 64  **          read
21dc0 20 66 72 6f 6d 20 7a 53 71 6c 20 69 73 20 72 65   from zSql is re
21dd0 61 64 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  ad up to the fir
21de0 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
21df0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31  or..**.** {H1301
21e00 34 7d 20 49 66 20 74 68 65 20 6e 42 79 74 65 20  4} If the nByte 
21e10 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
21e20 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21e30 64 62 2c 7a 53 71 6c 2c 6e 42 79 74 65 2c 2e 2e  db,zSql,nByte,..
21e40 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
21e50 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
21e60 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
21e70 2c 20 74 68 65 6e 20 61 74 20 6d 6f 73 74 20 6e  , then at most n
21e80 42 79 74 65 73 20 62 79 74 65 73 20 6f 66 0a 2a  Bytes bytes of.*
21e90 2a 20 20 20 20 20 20 20 20 20 20 53 51 4c 20 74  *          SQL t
21ea0 65 78 74 20 69 73 20 72 65 61 64 20 66 72 6f 6d  ext is read from
21eb0 20 7a 53 71 6c 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31   zSql..**.** {H1
21ec0 33 30 31 35 7d 20 49 6e 20 5b 73 71 6c 69 74 65  3015} In [sqlite
21ed0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 64 62 2c  3_prepare_v2(db,
21ee0 7a 53 71 6c 2c 4e 2c 50 2c 70 7a 54 61 69 6c 29  zSql,N,P,pzTail)
21ef0 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
21f00 74 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ts.**          i
21f10 66 20 74 68 65 20 7a 53 71 6c 20 69 6e 70 75 74  f the zSql input
21f20 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6d   text contains m
21f30 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 53 51 4c  ore than one SQL
21f40 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20   statement.**   
21f50 20 20 20 20 20 20 20 61 6e 64 20 70 7a 54 61 69         and pzTai
21f60 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  l is not NULL, t
21f70 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
21f80 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
21f90 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
21fa0 66 69 72 73 74 20 62 79 74 65 20 70 61 73 74 20  first byte past 
21fb0 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
21fc0 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
21fd0 6e 74 20 69 6e 20 7a 53 71 6c 2e 0a 2a 2a 20 20  nt in zSql..**  
21fe0 20 20 20 20 20 20 20 20 3c 74 6f 64 6f 3e 57 68          <todo>Wh
21ff0 61 74 20 64 6f 65 73 20 2a 70 7a 54 61 69 6c 20  at does *pzTail 
22000 70 6f 69 6e 74 20 74 6f 20 69 66 20 74 68 65 72  point to if ther
22010 65 20 69 73 20 6f 6e 65 20 73 74 61 74 65 6d 65  e is one stateme
22020 6e 74 3f 3c 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a  nt?</todo>.**.**
22030 20 7b 48 31 33 30 31 36 7d 20 41 20 73 75 63 63   {H13016} A succ
22040 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
22050 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
22060 76 32 28 64 62 2c 7a 53 71 6c 2c 4e 2c 70 70 53  v2(db,zSql,N,ppS
22070 74 6d 74 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  tmt,...)].**    
22080 20 20 20 20 20 20 6f 72 20 6f 6e 65 20 6f 66 20        or one of 
22090 69 74 73 20 76 61 72 69 61 6e 74 73 20 77 72 69  its variants wri
220a0 74 65 73 20 69 6e 74 6f 20 2a 70 70 53 74 6d 74  tes into *ppStmt
220b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
220c0 6e 65 77 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  new.**          
220d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
220e0 65 6e 74 5d 20 6f 72 20 61 20 70 6f 69 6e 74 65  ent] or a pointe
220f0 72 20 74 6f 20 4e 55 4c 4c 20 69 66 20 7a 53 71  r to NULL if zSq
22100 6c 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 20 20  l contains.**   
22110 20 20 20 20 20 20 20 6e 6f 74 68 69 6e 67 20 6f         nothing o
22120 74 68 65 72 20 74 68 61 6e 20 77 68 69 74 65 73  ther than whites
22130 70 61 63 65 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  pace or comments
22140 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 31 39 7d  ..**.** {H13019}
22150 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   The [sqlite3_pr
22160 65 70 61 72 65 5f 76 32 28 29 5d 20 69 6e 74 65  epare_v2()] inte
22170 72 66 61 63 65 20 61 6e 64 20 69 74 73 20 76 61  rface and its va
22180 72 69 61 6e 74 73 20 72 65 74 75 72 6e 0a 2a 2a  riants return.**
22190 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
221a0 45 5f 4f 4b 5d 20 6f 72 20 61 6e 20 61 70 70 72  E_OK] or an appr
221b0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
221c0 6f 64 65 5d 20 75 70 6f 6e 20 66 61 69 6c 75 72  ode] upon failur
221d0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 30 32 31  e..**.** {H13021
221e0 7d 20 42 65 66 6f 72 65 20 5b 73 71 6c 69 74 65  } Before [sqlite
221f0 33 5f 70 72 65 70 61 72 65 28 64 62 2c 7a 53 71  3_prepare(db,zSq
22200 6c 2c 6e 42 79 74 65 2c 70 70 53 74 6d 74 2c 70  l,nByte,ppStmt,p
22210 7a 54 61 69 6c 29 5d 20 6f 72 20 69 74 73 0a 2a  zTail)] or its.*
22220 2a 20 20 20 20 20 20 20 20 20 20 76 61 72 69 61  *          varia
22230 6e 74 73 20 72 65 74 75 72 6e 73 20 61 6e 20 65  nts returns an e
22240 72 72 6f 72 20 28 61 6e 79 20 76 61 6c 75 65 20  rror (any value 
22250 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
22260 54 45 5f 4f 4b 5d 29 2c 0a 2a 2a 20 20 20 20 20  TE_OK]),.**     
22270 20 20 20 20 20 74 68 65 79 20 66 69 72 73 74 20       they first 
22280 73 65 74 20 2a 70 70 53 74 6d 74 20 74 6f 20 4e  set *ppStmt to N
22290 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
222a0 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
222b0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
222c0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
222d0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
222e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
222f0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
22300 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
22310 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
22320 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
22330 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
22340 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
22350 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
22360 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
22370 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
22380 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
22390 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
223a0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
223b0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
223c0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
223d0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
223e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
223f0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
22400 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
22410 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
22420 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
22430 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
22440 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
22450 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
22460 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
22470 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
22480 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
22490 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
224a0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
224b0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
224c0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
224d0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
224e0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
224f0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
22500 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
22510 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
22520 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
22530 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
22540 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
22550 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
22560 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
22570 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
22580 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
22590 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
225a0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
225b0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
225c0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
225d0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
225e0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
225f0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
22600 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
22610 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
22620 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
22630 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
22640 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
22650 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
22660 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
22670 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
22680 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
22690 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
226a0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
226b0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
226c0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
226d0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
226e0 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
226f0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
22700 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
22710 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
22720 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
22730 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
22740 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
22750 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
22760 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
22770 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
22780 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
22790 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
227a0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
227b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
227c0 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
227d0 65 6d 65 6e 74 20 53 51 4c 20 7b 48 31 33 31 30  ement SQL {H1310
227e0 30 7d 20 3c 48 31 33 30 30 30 3e 0a 2a 2a 0a 2a  0} <H13000>.**.*
227f0 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
22800 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
22810 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64  retrieve a saved
22820 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69   copy of the ori
22830 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78  ginal.** SQL tex
22840 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
22850 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
22860 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20  tement] if that 
22870 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a  statement was.**
22880 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
22890 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
228a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
228b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
228c0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
228d0 20 49 4e 56 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a   INVARIANTS:.**.
228e0 2a 2a 20 7b 48 31 33 31 30 31 7d 20 49 66 20 74  ** {H13101} If t
228f0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
22900 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64 20 61  tement] passed a
22910 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
22920 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
22930 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 77 61  qlite3_sql()] wa
22940 73 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  s compiled using
22950 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
22960 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
22970 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  r.**          [s
22980 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
22990 5f 76 32 28 29 5d 2c 20 74 68 65 6e 20 5b 73 71  _v2()], then [sq
229a0 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20 72 65 74  lite3_sql()] ret
229b0 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  urns.**         
229c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
229d0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
229e0 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e  string containin
229f0 67 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  g a UTF-8 render
22a00 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
22a10 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  of the original 
22a20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
22a30 2a 0a 2a 2a 20 7b 48 31 33 31 30 32 7d 20 49 66  *.** {H13102} If
22a40 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
22a50 74 61 74 65 6d 65 6e 74 5d 20 70 61 73 73 65 64  tatement] passed
22a60 20 61 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   as the argument
22a70 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
22a80 5b 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 5d 20  [sqlite3_sql()] 
22a90 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  was compiled usi
22aa0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
22ab0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
22ac0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
22ad0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
22ae0 29 5d 2c 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  )], then [sqlite
22af0 33 5f 73 71 6c 28 29 5d 20 72 65 74 75 72 6e 73  3_sql()] returns
22b00 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
22b10 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 31 30 33 7d 20  .**.** {H13103} 
22b20 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72  The string retur
22b30 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
22b40 73 71 6c 28 53 29 5d 20 69 73 20 76 61 6c 69 64  sql(S)] is valid
22b50 20 75 6e 74 69 6c 20 74 68 65 0a 2a 2a 20 20 20   until the.**   
22b60 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64         [prepared
22b70 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 73   statement] S is
22b80 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 5b   deleted using [
22b90 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
22ba0 28 53 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  (S)]..*/.const c
22bb0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
22bc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
22bd0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
22be0 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61  PI3REF: Dynamica
22bf0 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20  lly Typed Value 
22c00 4f 62 6a 65 63 74 20 7b 48 31 35 30 30 30 7d 20  Object {H15000} 
22c10 3c 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S20200>.** KEYW
22c20 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
22c30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
22c40 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
22c50 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
22c60 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
22c70 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
22c80 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
22c90 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
22ca0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
22cb0 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
22cc0 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
22cd0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
22ce0 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
22cf0 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
22d00 2e 20 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20  . Values stored 
22d10 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  in sqlite3_value
22d20 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20   objects.** can 
22d30 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f  be integers, flo
22d40 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
22d50 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f  es, strings, BLO
22d60 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a  Bs, or NULL..**.
22d70 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61  ** An sqlite3_va
22d80 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62  lue object may b
22d90 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63  e either "protec
22da0 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65  ted" or "unprote
22db0 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69  cted"..** Some i
22dc0 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
22dd0 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  e a protected sq
22de0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74  lite3_value.  Ot
22df0 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  her interfaces.*
22e00 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69  * will accept ei
22e10 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64  ther a protected
22e20 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74   or an unprotect
22e30 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
22e40 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72  ..** Every inter
22e50 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74  face that accept
22e60 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  s sqlite3_value 
22e70 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66  arguments specif
22e80 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f  ies.** whether o
22e90 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65  r not it require
22ea0 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71  s a protected sq
22eb0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
22ec0 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
22ed0 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
22ee0 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
22ef0 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
22f00 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
22f10 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e   held.  A intern
22f20 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
22f30 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
22f40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
22f50 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
22f60 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
22f70 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
22f80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
22f90 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
22fa0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
22fb0 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
22fc0 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
22fd0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
22fe0 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b  FE=0] and with [
22ff0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
23000 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20  fe()] returning 
23010 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69  0).** or if SQLi
23020 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65  te is run in one
23030 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65   of reduced mute
23040 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c  x modes .** [SQL
23050 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
23060 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c  ETHREAD] or [SQL
23070 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
23080 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20  THREAD].** then 
23090 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74  there is no dist
230a0 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
230b0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
230c0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
230d0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
230e0 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20  ts and they can 
230f0 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  be used intercha
23100 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65  ngeably.  Howeve
23110 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75  r,.** for maximu
23120 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69  m code portabili
23130 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ty it is recomme
23140 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
23150 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20  ations.** still 
23160 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
23170 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 62 65 74  tion between bet
23180 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
23190 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
231a0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
231b0 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65  objects even whe
231c0 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72  n not strictly r
231d0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
231e0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
231f0 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
23200 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
23210 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
23220 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
23230 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
23240 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
23250 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
23260 74 65 63 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73  tected..** The s
23270 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
23280 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
23290 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
232a0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
232b0 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
232c0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
232d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
232e0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
232f0 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
23300 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
23310 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
23320 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
23330 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
23340 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
23350 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
23360 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
23370 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
23380 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
23390 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
233a0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
233b0 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
233c0 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
233d0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
233e0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
233f0 6a 65 63 74 20 7b 48 31 36 30 30 31 7d 20 3c 53  ject {H16001} <S
23400 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
23410 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63   context in whic
23420 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  h an SQL functio
23430 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74  n executes is st
23440 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71  ored in an.** sq
23450 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
23460 6a 65 63 74 2e 20 20 41 20 70 6f 69 6e 74 65 72  ject.  A pointer
23470 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
23480 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
23490 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
234a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
234b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
234c0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
234d0 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
234e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
234f0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
23500 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
23510 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
23520 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
23530 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
23540 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
23550 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
23560 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
23570 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
23580 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
23590 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
235a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
235b0 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
235c0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
235d0 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
235e0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
235f0 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
23600 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
23610 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
23620 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
23630 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
23640 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
23650 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
23660 6e 74 73 20 7b 48 31 33 35 30 30 7d 20 3c 53 37  nts {H13500} <S7
23670 30 33 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0300>.** KEYWORD
23680 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
23690 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
236a0 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
236b0 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
236c0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
236d0 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
236e0 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
236f0 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
23700 0a 2a 2a 20 49 6e 20 74 68 65 20 53 51 4c 20 73  .** In the SQL s
23710 74 72 69 6e 67 73 20 69 6e 70 75 74 20 74 6f 20  trings input to 
23720 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23730 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76  _v2()] and its v
23740 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65  ariants,.** lite
23750 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c  rals may be repl
23760 61 63 65 64 20 62 79 20 61 20 70 61 72 61 6d 65  aced by a parame
23770 74 65 72 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  ter in one of th
23780 65 73 65 20 66 6f 72 6d 73 3a 0a 2a 2a 0a 2a 2a  ese forms:.**.**
23790 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
237a0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
237b0 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
237c0 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
237d0 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
237e0 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 70  >.**.** In the p
237f0 61 72 61 6d 65 74 65 72 20 66 6f 72 6d 73 20 73  arameter forms s
23800 68 6f 77 6e 20 61 62 6f 76 65 20 4e 4e 4e 20 69  hown above NNN i
23810 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
23820 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56  eral,.** and VVV
23830 20 69 73 20 61 6e 20 61 6c 70 68 61 2d 6e 75 6d   is an alpha-num
23840 65 72 69 63 20 70 61 72 61 6d 65 74 65 72 20 6e  eric parameter n
23850 61 6d 65 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ame. The values 
23860 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
23870 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
23880 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
23890 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
238a0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
238b0 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
238c0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
238d0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
238e0 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
238f0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
23900 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
23910 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
23920 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
23930 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
23940 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
23950 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
23960 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
23970 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
23980 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
23990 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  iants..**.** The
239a0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
239b0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
239c0 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
239d0 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
239e0 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51   The leftmost SQ
239f0 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
23a00 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
23a10 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
23a20 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
23a30 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
23a40 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
23a50 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
23a60 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
23a70 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
23a80 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
23a90 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
23aa0 2a 20 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20  * The index for 
23ab0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73  named parameters
23ac0 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75   can be looked u
23ad0 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  p using the.** [
23ae0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
23af0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20  ameter_index()] 
23b00 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20  API if desired. 
23b10 20 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f   The index.** fo
23b20 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
23b30 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
23b40 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 54 68 65 20   of NNN..** The 
23b50 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
23b60 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
23b70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
23b80 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
23b90 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
23ba0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
23bb0 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
23bc0 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  : 999)..**.** Th
23bd0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
23be0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
23bf0 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
23c00 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e  ameter..**.** In
23c10 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
23c20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
23c30 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
23c40 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
23c50 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
23c60 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
23c70 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
23c80 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
23c90 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
23ca0 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
23cb0 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
23cc0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
23cd0 61 63 74 65 72 73 2e 0a 2a 2a 20 49 66 20 74 68  acters..** If th
23ce0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
23cf0 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
23d00 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
23d10 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
23d20 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
23d30 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
23d40 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
23d50 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  or..**.** The fi
23d60 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
23d70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
23d80 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
23d90 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
23da0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
23db0 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
23dc0 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
23dd0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
23de0 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
23df0 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
23e00 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
23e10 74 2e 20 49 66 20 74 68 65 20 66 69 66 74 68 20  t. If the fifth 
23e20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
23e30 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
23e40 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
23e50 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
23e60 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
23e70 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
23e80 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
23e90 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
23ea0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
23eb0 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 49 66   be freed..** If
23ec0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
23ed0 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
23ee0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
23ef0 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
23f00 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
23f10 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
23f20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
23f30 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
23f40 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
23f50 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
23f60 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  returns..**.** T
23f70 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
23f80 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
23f90 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
23fa0 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
23fb0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
23fc0 74 68 20 7a 65 72 6f 65 73 2e 20 20 41 20 7a 65  th zeroes.  A ze
23fd0 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
23fe0 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
23ff0 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
24000 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
24010 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65   its size) while
24020 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
24030 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
24040 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
24050 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
24060 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
24070 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
24080 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
24090 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20  ritten using.** 
240a0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
240b0 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
240c0 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69   BLOB I/O] routi
240d0 6e 65 73 2e 0a 2a 2a 20 41 20 6e 65 67 61 74 69  nes..** A negati
240e0 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
240f0 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
24100 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
24110 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54  th BLOB..**.** T
24120 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
24130 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  *() routines mus
24140 74 20 62 65 20 63 61 6c 6c 65 64 20 61 66 74 65  t be called afte
24150 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
24160 65 70 61 72 65 5f 76 32 28 29 5d 20 28 61 6e 64  epare_v2()] (and
24170 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 6f   its variants) o
24180 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
24190 28 29 5d 20 61 6e 64 0a 2a 2a 20 62 65 66 6f 72  ()] and.** befor
241a0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
241b0 29 5d 2e 0a 2a 2a 20 42 69 6e 64 69 6e 67 73 20  )]..** Bindings 
241c0 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
241d0 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
241e0 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
241f0 2e 0a 2a 2a 20 55 6e 62 6f 75 6e 64 20 70 61 72  ..** Unbound par
24200 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
24210 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
24220 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
24230 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
24240 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
24250 65 73 73 20 6f 72 20 61 6e 20 65 72 72 6f 72 20  ess or an error 
24260 63 6f 64 65 20 69 66 0a 2a 2a 20 61 6e 79 74 68  code if.** anyth
24270 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 20  ing goes wrong. 
24280 20 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20   [SQLITE_RANGE] 
24290 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  is returned if t
242a0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
242b0 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
242c0 72 61 6e 67 65 2e 20 20 5b 53 51 4c 49 54 45 5f  range.  [SQLITE_
242d0 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
242e0 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
242f0 61 69 6c 73 2e 0a 2a 2a 20 5b 53 51 4c 49 54 45  ails..** [SQLITE
24300 5f 4d 49 53 55 53 45 5d 20 6d 69 67 68 74 20 62  _MISUSE] might b
24310 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  e returned if th
24320 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
24330 20 63 61 6c 6c 65 64 20 6f 6e 20 61 0a 2a 2a 20   called on a.** 
24340 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
24350 74 68 61 74 20 69 73 20 74 68 65 20 77 72 6f 6e  that is the wron
24360 67 20 73 74 61 74 65 20 6f 72 20 77 68 69 63 68  g state or which
24370 20 68 61 73 20 61 6c 72 65 61 64 79 20 62 65 65   has already bee
24380 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20  n finalized..** 
24390 44 65 74 65 63 74 69 6f 6e 20 6f 66 20 6d 69 73  Detection of mis
243a0 75 73 65 20 69 73 20 75 6e 72 65 6c 69 61 62 6c  use is unreliabl
243b0 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  e.  Applications
243c0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 64 65 70 65   should not depe
243d0 6e 64 0a 2a 2a 20 6f 6e 20 53 51 4c 49 54 45 5f  nd.** on SQLITE_
243e0 4d 49 53 55 53 45 20 72 65 74 75 72 6e 73 2e 20  MISUSE returns. 
243f0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 69   SQLITE_MISUSE i
24400 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 69 6e  s intended to in
24410 64 69 63 61 74 65 20 61 0a 2a 2a 20 61 20 6c 6f  dicate a.** a lo
24420 67 69 63 20 65 72 72 6f 72 20 69 6e 20 74 68 65  gic error in the
24430 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 46   application.  F
24440 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
24450 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
24460 2a 20 70 61 6e 69 63 20 72 61 74 68 65 72 20 74  * panic rather t
24470 68 61 6e 20 72 65 74 75 72 6e 20 53 51 4c 49 54  han return SQLIT
24480 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 0a 2a 2a 20  E_MISUSE..**.** 
24490 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
244a0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
244b0 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
244c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
244d0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
244e0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
244f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
24500 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  x()]..**.** INVA
24510 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
24520 31 33 35 30 36 7d 20 54 68 65 20 5b 53 51 4c 20  13506} The [SQL 
24530 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
24540 65 72 5d 20 72 65 63 6f 67 6e 69 7a 65 73 20 74  er] recognizes t
24550 6f 6b 65 6e 73 20 6f 66 20 74 68 65 20 66 6f 72  okens of the for
24560 6d 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 22  ms.**          "
24570 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 24 56 56  ?", "?NNN", "$VV
24580 56 22 2c 20 22 3a 56 56 56 22 2c 20 61 6e 64 20  V", ":VVV", and 
24590 22 40 56 56 56 22 20 61 73 20 53 51 4c 20 70 61  "@VVV" as SQL pa
245a0 72 61 6d 65 74 65 72 73 2c 0a 2a 2a 20 20 20 20  rameters,.**    
245b0 20 20 20 20 20 20 77 68 65 72 65 20 4e 4e 4e 20        where NNN 
245c0 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20  is any sequence 
245d0 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 64  of one or more d
245e0 69 67 69 74 73 0a 2a 2a 20 20 20 20 20 20 20 20  igits.**        
245f0 20 20 61 6e 64 20 77 68 65 72 65 20 56 56 56 20    and where VVV 
24600 69 73 20 61 6e 79 20 73 65 71 75 65 6e 63 65 20  is any sequence 
24610 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 61  of one or more a
24620 6c 70 68 61 6e 75 6d 65 72 69 63 0a 2a 2a 20 20  lphanumeric.**  
24630 20 20 20 20 20 20 20 20 63 68 61 72 61 63 74 65          characte
24640 72 73 20 6f 72 20 22 3a 3a 22 20 6f 70 74 69 6f  rs or "::" optio
24650 6e 61 6c 6c 79 20 66 6f 6c 6c 6f 77 65 64 20 62  nally followed b
24660 79 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  y a string conta
24670 69 6e 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20  ining.**        
24680 20 20 6e 6f 20 73 70 61 63 65 73 20 61 6e 64 20    no spaces and 
24690 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e  contained within
246a0 20 70 61 72 65 6e 74 68 65 73 65 73 2e 0a 2a 2a   parentheses..**
246b0 0a 2a 2a 20 7b 48 31 33 35 30 39 7d 20 54 68 65  .** {H13509} The
246c0 20 69 6e 69 74 69 61 6c 20 76 61 6c 75 65 20 6f   initial value o
246d0 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
246e0 65 72 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  er is NULL..**.*
246f0 2a 20 7b 48 31 33 35 31 32 7d 20 54 68 65 20 69  * {H13512} The i
24700 6e 64 65 78 20 6f 66 20 61 6e 20 22 3f 22 20 53  ndex of an "?" S
24710 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
24720 6f 6e 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20  one larger than 
24730 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
24740 6c 61 72 67 65 73 74 20 69 6e 64 65 78 20 6f 66  largest index of
24750 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
24760 6f 20 74 68 65 20 6c 65 66 74 2c 20 6f 72 20 31  o the left, or 1
24770 20 69 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   if.**          
24780 74 68 65 20 22 3f 22 20 69 73 20 74 68 65 20 6c  the "?" is the l
24790 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
247a0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  meter..**.** {H1
247b0 33 35 31 35 7d 20 54 68 65 20 69 6e 64 65 78 20  3515} The index 
247c0 6f 66 20 61 6e 20 22 3f 4e 4e 4e 22 20 53 51 4c  of an "?NNN" SQL
247d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
247e0 65 20 69 6e 74 65 67 65 72 20 4e 4e 4e 2e 0a 2a  e integer NNN..*
247f0 2a 0a 2a 2a 20 7b 48 31 33 35 31 38 7d 20 54 68  *.** {H13518} Th
24800 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 22 3a  e index of an ":
24810 56 56 56 22 2c 20 22 24 56 56 56 22 2c 20 6f 72  VVV", "$VVV", or
24820 20 22 40 56 56 56 22 20 53 51 4c 20 70 61 72 61   "@VVV" SQL para
24830 6d 65 74 65 72 20 69 73 0a 2a 2a 20 20 20 20 20  meter is.**     
24840 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 61 73       the same as
24850 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 6c 65   the index of le
24860 66 74 6d 6f 73 74 20 6f 63 63 75 72 72 65 6e 63  ftmost occurrenc
24870 65 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  es of the same.*
24880 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
24890 65 74 65 72 2c 20 6f 72 20 6f 6e 65 20 6d 6f 72  eter, or one mor
248a0 65 20 74 68 61 6e 20 74 68 65 20 6c 61 72 67 65  e than the large
248b0 73 74 20 69 6e 64 65 78 20 6f 76 65 72 20 61 6c  st index over al
248c0 6c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 70 61  l.**          pa
248d0 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
248e0 6c 65 66 74 20 69 66 20 74 68 69 73 20 69 73 20  left if this is 
248f0 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
24900 65 6e 63 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  ence.**         
24910 20 6f 66 20 74 68 69 73 20 70 61 72 61 6d 65 74   of this paramet
24920 65 72 2c 20 6f 72 20 31 20 69 66 20 74 68 69 73  er, or 1 if this
24930 20 69 73 20 74 68 65 20 6c 65 66 74 6d 6f 73 74   is the leftmost
24940 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
24950 2a 20 7b 48 31 33 35 32 31 7d 20 54 68 65 20 5b  * {H13521} The [
24960 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
24970 6d 70 69 6c 65 72 5d 20 66 61 69 6c 73 20 77 69  mpiler] fails wi
24980 74 68 20 61 6e 20 5b 53 51 4c 49 54 45 5f 52 41  th an [SQLITE_RA
24990 4e 47 45 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  NGE].**         
249a0 20 65 72 72 6f 72 20 69 66 20 74 68 65 20 69 6e   error if the in
249b0 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
249c0 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
249d0 74 68 61 6e 20 31 0a 2a 2a 20 20 20 20 20 20 20  than 1.**       
249e0 20 20 20 6f 72 20 67 72 65 61 74 65 72 20 74 68     or greater th
249f0 61 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  an the compile-t
24a00 69 6d 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56  ime SQLITE_MAX_V
24a10 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 0a 2a  ARIABLE_NUMBER.*
24a20 2a 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d  *          param
24a30 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  eter..**.** {H13
24a40 35 32 34 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73  524} Calls to [s
24a50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
24a60 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28   | sqlite3_bind(
24a70 53 2c 4e 2c 56 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20  S,N,V,...)].**  
24a80 20 20 20 20 20 20 20 20 61 73 73 6f 63 69 61 74          associat
24a90 65 20 74 68 65 20 76 61 6c 75 65 20 56 20 77 69  e the value V wi
24aa0 74 68 20 61 6c 6c 20 53 51 4c 20 70 61 72 61 6d  th all SQL param
24ab0 65 74 65 72 73 20 68 61 76 69 6e 67 20 61 6e 0a  eters having an.
24ac0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 64 65  **          inde
24ad0 78 20 6f 66 20 4e 20 69 6e 20 74 68 65 20 5b 70  x of N in the [p
24ae0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24af0 74 5d 20 53 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  t] S..**.** {H13
24b00 35 32 37 7d 20 43 61 6c 6c 73 20 74 6f 20 5b 73  527} Calls to [s
24b10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
24b20 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28   | sqlite3_bind(
24b30 53 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  S,N,...)].**    
24b40 20 20 20 20 20 20 6f 76 65 72 72 69 64 65 20 70        override p
24b50 72 69 6f 72 20 63 61 6c 6c 73 20 77 69 74 68 20  rior calls with 
24b60 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 73 20  the same values 
24b70 6f 66 20 53 20 61 6e 64 20 4e 2e 0a 2a 2a 0a 2a  of S and N..**.*
24b80 2a 20 7b 48 31 33 35 33 30 7d 20 42 69 6e 64 69  * {H13530} Bindi
24b90 6e 67 73 20 65 73 74 61 62 6c 69 73 68 65 64 20  ngs established 
24ba0 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  by [sqlite3_bind
24bb0 5f 74 65 78 74 20 7c 20 73 71 6c 69 74 65 33 5f  _text | sqlite3_
24bc0 62 69 6e 64 28 53 2c 2e 2e 2e 29 5d 0a 2a 2a 20  bind(S,...)].** 
24bd0 20 20 20 20 20 20 20 20 20 70 65 72 73 69 73 74           persist
24be0 20 61 63 72 6f 73 73 20 63 61 6c 6c 73 20 74 6f   across calls to
24bf0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
24c00 53 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35  S)]..**.** {H135
24c10 33 33 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20  33} In calls to 
24c20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
24c30 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a  ob(S,N,V,L,D)],.
24c40 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
24c50 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 53  ite3_bind_text(S
24c60 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a  ,N,V,L,D)], or.*
24c70 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
24c80 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
24c90 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69  S,N,V,L,D)] SQLi
24ca0 74 65 20 62 69 6e 64 73 20 74 68 65 20 66 69 72  te binds the fir
24cb0 73 74 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  st L.**         
24cc0 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c   bytes of the BL
24cd0 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 70 6f 69  OB or string poi
24ce0 6e 74 65 64 20 74 6f 20 62 79 20 56 2c 20 77 68  nted to by V, wh
24cf0 65 6e 20 4c 0a 2a 2a 20 20 20 20 20 20 20 20 20  en L.**         
24d00 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
24d10 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 33 36 7d  ..**.** {H13536}
24d20 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
24d30 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
24d40 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 6f 72 0a 2a  S,N,V,L,D)] or.*
24d50 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69  *          [sqli
24d60 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
24d70 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 53 51 4c 69  S,N,V,L,D)] SQLi
24d80 74 65 20 62 69 6e 64 73 20 63 68 61 72 61 63 74  te binds charact
24d90 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ers.**          
24da0 66 72 6f 6d 20 56 20 74 68 72 6f 75 67 68 20 74  from V through t
24db0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
24dc0 61 72 61 63 74 65 72 20 77 68 65 6e 20 4c 20 69  aracter when L i
24dd0 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  s negative..**.*
24de0 2a 20 7b 48 31 33 35 33 39 7d 20 49 6e 20 63 61  * {H13539} In ca
24df0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
24e00 62 69 6e 64 5f 62 6c 6f 62 28 53 2c 4e 2c 56 2c  bind_blob(S,N,V,
24e10 4c 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  L,D)],.**       
24e20 20 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64     [sqlite3_bind
24e30 5f 74 65 78 74 28 53 2c 4e 2c 56 2c 4c 2c 44 29  _text(S,N,V,L,D)
24e40 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  ], or.**        
24e50 20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f    [sqlite3_bind_
24e60 74 65 78 74 31 36 28 53 2c 4e 2c 56 2c 4c 2c 44  text16(S,N,V,L,D
24e70 29 5d 20 77 68 65 6e 20 44 20 69 73 20 74 68 65  )] when D is the
24e80 20 73 70 65 63 69 61 6c 0a 2a 2a 20 20 20 20 20   special.**     
24e90 20 20 20 20 20 63 6f 6e 73 74 61 6e 74 20 5b 53       constant [S
24ea0 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 53  QLITE_STATIC], S
24eb0 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
24ec0 61 74 20 74 68 65 20 76 61 6c 75 65 20 56 0a 2a  at the value V.*
24ed0 2a 20 20 20 20 20 20 20 20 20 20 69 73 20 68 65  *          is he
24ee0 6c 64 20 69 6e 20 73 74 61 74 69 63 20 75 6e 6d  ld in static unm
24ef0 61 6e 61 67 65 64 20 73 70 61 63 65 20 74 68 61  anaged space tha
24f00 74 20 77 69 6c 6c 20 6e 6f 74 20 63 68 61 6e 67  t will not chang
24f10 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 75  e.**          du
24f20 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
24f30 65 20 6f 66 20 74 68 65 20 62 69 6e 64 69 6e 67  e of the binding
24f40 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 35 34 32 7d  ..**.** {H13542}
24f50 20 49 6e 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71   In calls to [sq
24f60 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
24f70 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 0a 2a 2a 20  S,N,V,L,D)],.** 
24f80 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
24f90 33 5f 62 69 6e 64 5f 74 65 78 74 28 53 2c 4e 2c  3_bind_text(S,N,
24fa0 56 2c 4c 2c 44 29 5d 2c 20 6f 72 0a 2a 2a 20 20  V,L,D)], or.**  
24fb0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
24fc0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 53 2c 4e  _bind_text16(S,N
24fd0 2c 56 2c 4c 2c 44 29 5d 20 77 68 65 6e 20 44 20  ,V,L,D)] when D 
24fe0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 0a 2a  is the special.*
24ff0 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 73 74  *          const
25000 61 6e 74 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  ant [SQLITE_TRAN
25010 53 49 45 4e 54 5d 2c 20 74 68 65 20 72 6f 75 74  SIENT], the rout
25020 69 6e 65 20 6d 61 6b 65 73 20 61 0a 2a 2a 20 20  ine makes a.**  
25030 20 20 20 20 20 20 20 20 70 72 69 76 61 74 65 20          private 
25040 63 6f 70 79 20 6f 66 20 74 68 65 20 76 61 6c 75  copy of the valu
25050 65 20 56 20 62 65 66 6f 72 65 20 69 74 20 72 65  e V before it re
25060 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  turns..**.** {H1
25070 33 35 34 35 7d 20 49 6e 20 63 61 6c 6c 73 20 74  3545} In calls t
25080 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
25090 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d  blob(S,N,V,L,D)]
250a0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  ,.**          [s
250b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
250c0 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 2c 20 6f 72  (S,N,V,L,D)], or
250d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
250e0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
250f0 36 28 53 2c 4e 2c 56 2c 4c 2c 44 29 5d 20 77 68  6(S,N,V,L,D)] wh
25100 65 6e 20 44 20 69 73 20 61 20 70 6f 69 6e 74 65  en D is a pointe
25110 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  r to.**         
25120 20 61 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c   a function, SQL
25130 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 61 74  ite invokes that
25140 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 64 65 73   function to des
25150 74 72 6f 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  troy the.**     
25160 20 20 20 20 20 76 61 6c 75 65 20 56 20 61 66 74       value V aft
25170 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
25180 65 64 20 75 73 69 6e 67 20 74 68 65 20 76 61 6c  ed using the val
25190 75 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ue V..**.** {H13
251a0 35 34 38 7d 20 49 6e 20 63 61 6c 6c 73 20 74 6f  548} In calls to
251b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a   [sqlite3_bind_z
251c0 65 72 6f 62 6c 6f 62 28 53 2c 4e 2c 56 2c 4c 29  eroblob(S,N,V,L)
251d0 5d 20 74 68 65 20 76 61 6c 75 65 20 62 6f 75 6e  ] the value boun
251e0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  d.**          is
251f0 20 61 20 42 4c 4f 42 20 6f 66 20 4c 20 62 79 74   a BLOB of L byt
25200 65 73 2c 20 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  es, or a zero-le
25210 6e 67 74 68 20 42 4c 4f 42 20 69 66 20 4c 20 69  ngth BLOB if L i
25220 73 20 6e 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a  s negative..**.*
25230 2a 20 7b 48 31 33 35 35 31 7d 20 49 6e 20 63 61  * {H13551} In ca
25240 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
25250 62 69 6e 64 5f 76 61 6c 75 65 28 53 2c 4e 2c 56  bind_value(S,N,V
25260 29 5d 20 74 68 65 20 56 20 61 72 67 75 6d 65 6e  )] the V argumen
25270 74 20 6d 61 79 0a 2a 2a 20 20 20 20 20 20 20 20  t may.**        
25280 20 20 62 65 20 65 69 74 68 65 72 20 61 20 5b 70    be either a [p
25290 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
252a0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6f  _value] object o
252b0 72 20 61 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  r an.**         
252c0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
252d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
252e0 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ect..*/.int sqli
252f0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
25300 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
25310 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
25320 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
25330 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
25340 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
25350 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
25360 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
25370 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
25380 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
25390 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
253a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
253b0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
253c0 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
253d0 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
253e0 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
253f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
25400 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
25410 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
25420 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
25430 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
25440 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
25450 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
25460 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
25470 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
25480 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
25490 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
254a0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
254b0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
254c0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
254d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
254e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
254f0 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
25500 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
25510 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
25520 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
25530 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
25540 20 7b 48 31 33 36 30 30 7d 20 3c 53 37 30 33 30   {H13600} <S7030
25550 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  0>.**.** This ro
25560 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65  utine can be use
25570 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
25580 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72  mber of [SQL par
25590 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61  ameters].** in a
255a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
255b0 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61  ment].  SQL para
255c0 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e  meters are token
255d0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  s of the.** form
255e0 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a   "?", "?NNN", ":
255f0 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72  AAA", "$AAA", or
25600 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72   "@AAA" that ser
25610 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f  ve as.** placeho
25620 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73  lders for values
25630 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74   that are [sqlit
25640 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
25650 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20  ound].** to the 
25660 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20  parameters at a 
25670 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  later time..**.*
25680 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61  * This routine a
25690 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  ctually returns 
256a0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
256b0 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d   largest (rightm
256c0 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ost).** paramete
256d0 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73  r. For all forms
256e0 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68   except ?NNN, th
256f0 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f  is will correspo
25700 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d  nd to the.** num
25710 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61  ber of unique pa
25720 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61  rameters.  If pa
25730 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
25740 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64 2c 0a 2a  ?NNN are used,.*
25750 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
25760 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
25770 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
25780 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
25790 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
257a0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
257b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
257c0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
257d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
257e0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
257f0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
25800 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 30  TS:.**.** {H1360
25810 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  1} The [sqlite3_
25820 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
25830 6f 75 6e 74 28 53 29 5d 20 69 6e 74 65 72 66 61  ount(S)] interfa
25840 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20  ce returns.**   
25850 20 20 20 20 20 20 20 74 68 65 20 6c 61 72 67 65         the large
25860 73 74 20 69 6e 64 65 78 20 6f 66 20 61 6c 6c 20  st index of all 
25870 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 69  SQL parameters i
25880 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  n the.**        
25890 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
258a0 65 6d 65 6e 74 5d 20 53 2c 20 6f 72 20 30 20 69  ement] S, or 0 i
258b0 66 20 53 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  f S contains no 
258c0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  SQL parameters..
258d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
258e0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
258f0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
25900 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
25910 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
25920 6f 73 74 20 50 61 72 61 6d 65 74 65 72 20 7b 48  ost Parameter {H
25930 31 33 36 32 30 7d 20 3c 53 37 30 33 30 30 3e 0a  13620} <S70300>.
25940 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
25950 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
25960 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 61 6d 65  nter to the name
25970 20 6f 66 20 74 68 65 20 6e 2d 74 68 0a 2a 2a 20   of the n-th.** 
25980 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
25990 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
259a0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 53 51  tatement]..** SQ
259b0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
259c0 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
259d0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
259e0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
259f0 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
25a00 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
25a10 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
25a20 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
25a30 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
25a40 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
25a50 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
25a60 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
25a70 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
25a80 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
25a90 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
25aa0 65 2e 0a 2a 2a 20 50 61 72 61 6d 65 74 65 72 73  e..** Parameters
25ab0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
25ac0 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
25ad0 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
25ae0 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
25af0 20 61 72 65 20 61 6c 73 6f 20 72 65 66 65 72 72   are also referr
25b00 65 64 20 74 6f 20 61 73 20 22 61 6e 6f 6e 79 6d  ed to as "anonym
25b10 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
25b20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
25b30 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
25b40 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
25b50 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
25b60 49 66 20 74 68 65 20 76 61 6c 75 65 20 6e 20 69  If the value n i
25b70 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
25b80 72 20 69 66 20 74 68 65 20 6e 2d 74 68 20 70 61  r if the n-th pa
25b90 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
25ba0 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
25bb0 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
25bc0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
25bd0 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
25be0 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
25bf0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
25c00 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
25c10 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
25c20 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
25c30 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
25c40 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
25c50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
25c60 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
25c70 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
25c80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
25c90 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
25ca0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
25cb0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
25cc0 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
25cd0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
25ce0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
25cf0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
25d00 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 32 31 7d  :.**.** {H13621}
25d10 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   The [sqlite3_bi
25d20 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
25d30 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
25d40 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
25d50 20 20 20 20 20 20 61 20 55 54 46 2d 38 20 72 65        a UTF-8 re
25d60 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 6e  ndering of the n
25d70 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 70  ame of the SQL p
25d80 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 20  arameter in.**  
25d90 20 20 20 20 20 20 20 20 74 68 65 20 5b 70 72 65          the [pre
25da0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25db0 20 53 20 68 61 76 69 6e 67 20 69 6e 64 65 78 20   S having index 
25dc0 4e 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20  N, or.**        
25dd0 20 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65 20    NULL if there 
25de0 69 73 20 6e 6f 20 53 51 4c 20 70 61 72 61 6d 65  is no SQL parame
25df0 74 65 72 20 77 69 74 68 20 69 6e 64 65 78 20 4e  ter with index N
25e00 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 20 20   or if the.**   
25e10 20 20 20 20 20 20 20 70 61 72 61 6d 65 74 65 72         parameter
25e20 20 77 69 74 68 20 69 6e 64 65 78 20 4e 20 69 73   with index N is
25e30 20 61 6e 20 61 6e 6f 6e 79 6d 6f 75 73 20 70 61   an anonymous pa
25e40 72 61 6d 65 74 65 72 20 22 3f 22 2e 0a 2a 2f 0a  rameter "?"..*/.
25e50 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
25e60 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
25e70 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
25e80 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
25e90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
25ea0 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
25eb0 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
25ec0 4e 61 6d 65 20 7b 48 31 33 36 34 30 7d 20 3c 53  Name {H13640} <S
25ed0 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74  70300>.**.** Ret
25ee0 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
25ef0 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
25f00 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
25f10 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20  .  The.** index 
25f20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
25f30 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
25f40 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
25f50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
25f60 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
25f70 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
25f80 28 29 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20  ()].  A zero.** 
25f90 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
25fa0 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
25fb0 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
25fc0 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
25fd0 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
25fe0 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
25ff0 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
26000 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
26010 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
26020 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
26030 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
26040 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
26050 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
26060 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
26070 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
26080 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
26090 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
260a0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
260b0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
260c0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
260d0 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
260e0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36 34 31 7d 20  .**.** {H13641} 
260f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  The [sqlite3_bin
26100 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
26110 78 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  x(S,N)] interfac
26120 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20  e returns.**    
26130 20 20 20 20 20 20 74 68 65 20 69 6e 64 65 78 20        the index 
26140 6f 66 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  of SQL parameter
26150 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
26160 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
26170 20 20 20 20 20 20 20 20 20 53 20 77 68 6f 73 65           S whose
26180 20 6e 61 6d 65 20 6d 61 74 63 68 65 73 20 74 68   name matches th
26190 65 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 4e  e UTF-8 string N
261a0 2c 20 6f 72 20 30 20 69 66 20 74 68 65 72 65 20  , or 0 if there 
261b0 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  is.**          n
261c0 6f 20 6d 61 74 63 68 2e 0a 2a 2f 0a 69 6e 74 20  o match..*/.int 
261d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
261e0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
261f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
26200 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
26210 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
26220 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
26230 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
26240 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33  d Statement {H13
26250 36 36 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a  660} <S70300>.**
26260 0a 2a 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f 20  .** Contrary to 
26270 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
26280 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
26290 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
262a0 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
262b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
262c0 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
262d0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
262e0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 55 73 65 20  tement]..** Use 
262f0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
26300 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
26310 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
26320 4c 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  L..**.** INVARIA
26330 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 36  NTS:.**.** {H136
26340 36 31 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  61} The [sqlite3
26350 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
26360 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
26370 73 65 74 73 20 61 6c 6c 20 53 51 4c 0a 2a 2a 20  sets all SQL.** 
26380 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65 74           paramet
26390 65 72 20 62 69 6e 64 69 6e 67 73 20 69 6e 20 74  er bindings in t
263a0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
263b0 74 65 6d 65 6e 74 5d 20 53 20 62 61 63 6b 20 74  tement] S back t
263c0 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
263d0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
263e0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
263f0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
26400 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
26410 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
26420 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37 31 30  sult Set {H13710
26430 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10700>.**.**
26440 20 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62   Return the numb
26450 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
26460 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
26470 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
26480 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
26490 74 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f  tement]. This ro
264a0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
264b0 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53  if pStmt is an S
264c0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
264d0 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
264e0 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65  turn data (for e
264f0 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
26500 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  E])..**.** INVAR
26510 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
26520 33 37 31 31 7d 20 54 68 65 20 5b 73 71 6c 69 74  3711} The [sqlit
26530 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
26540 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
26550 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
26560 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   of.**          
26570 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
26580 65 73 75 6c 74 20 73 65 74 20 67 65 6e 65 72 61  esult set genera
26590 74 65 64 20 62 79 20 74 68 65 20 5b 70 72 65 70  ted by the [prep
265a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
265b0 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  S,.**          o
265c0 72 20 30 20 69 66 20 53 20 64 6f 65 73 20 6e 6f  r 0 if S does no
265d0 74 20 67 65 6e 65 72 61 74 65 20 61 20 72 65 73  t generate a res
265e0 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20  ult set..*/.int 
265f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
26600 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
26610 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
26620 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
26630 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
26640 73 75 6c 74 20 53 65 74 20 7b 48 31 33 37 32 30  sult Set {H13720
26650 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10700>.**.**
26660 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
26670 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
26680 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
26690 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
266a0 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
266b0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
266c0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54  T] statement.  T
266d0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
266e0 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
266f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
26700 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
26710 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
26720 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
26730 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26740 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
26750 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
26760 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
26770 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
26780 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
26790 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
267a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
267b0 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
267c0 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
267d0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 54 68  T] statement. Th
267e0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
267f0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
26800 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 54 68 65  umn number.  The
26810 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
26820 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
26830 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64  .** The returned
26840 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
26850 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
26860 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61  ither the [prepa
26870 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
26880 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  * is destroyed b
26890 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
268a0 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
268b0 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
268c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
268d0 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
268e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
268f0 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
26900 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49   column..**.** I
26910 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
26920 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
26930 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
26940 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
26950 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
26960 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
26970 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
26980 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
26990 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
269a0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
269b0 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
269c0 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
269d0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
269e0 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
269f0 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
26a00 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
26a10 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
26a20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
26a30 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
26a40 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
26a50 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
26a60 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
26a70 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
26a80 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
26a90 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
26aa0 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
26ab0 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 31  S:.**.** {H13721
26ac0 7d 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69  } A successful i
26ad0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
26ae0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
26af0 5f 6e 61 6d 65 28 53 2c 4e 29 5d 0a 2a 2a 20 20  _name(S,N)].**  
26b00 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
26b10 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 61  e returns the na
26b20 6d 65 20 6f 66 20 74 68 65 20 4e 74 68 20 63 6f  me of the Nth co
26b30 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69 73  lumn (where 0 is
26b40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
26b50 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
26b60 29 20 66 6f 72 20 74 68 65 20 72 65 73 75 6c 74  ) for the result
26b70 20 73 65 74 20 6f 66 20 74 68 65 0a 2a 2a 20 20   set of the.**  
26b80 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72 65          [prepare
26b90 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 61  d statement] S a
26ba0 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  s a zero-termina
26bb0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
26bc0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 32 33 7d  ..**.** {H13723}
26bd0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
26be0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
26bf0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
26c00 6e 61 6d 65 31 36 28 53 2c 4e 29 5d 0a 2a 2a 20  name16(S,N)].** 
26c10 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
26c20 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
26c30 61 6d 65 20 6f 66 20 74 68 65 20 4e 74 68 20 63  ame of the Nth c
26c40 6f 6c 75 6d 6e 20 28 77 68 65 72 65 20 30 20 69  olumn (where 0 i
26c50 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  s.**          th
26c60 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
26c70 6e 29 20 66 6f 72 20 74 68 65 20 72 65 73 75 6c  n) for the resul
26c80 74 20 73 65 74 20 6f 66 20 74 68 65 0a 2a 2a 20  t set of the.** 
26c90 20 20 20 20 20 20 20 20 20 5b 70 72 65 70 61 72           [prepar
26ca0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
26cb0 61 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  as a zero-termin
26cc0 61 74 65 64 20 55 54 46 2d 31 36 20 73 74 72 69  ated UTF-16 stri
26cd0 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ng.**          i
26ce0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
26cf0 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  e order..**.** {
26d00 48 31 33 37 32 34 7d 20 54 68 65 20 5b 73 71 6c  H13724} The [sql
26d10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
26d20 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
26d30 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
26d40 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  ].**          in
26d50 74 65 72 66 61 63 65 73 20 72 65 74 75 72 6e 20  terfaces return 
26d60 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
26d70 66 20 74 68 65 79 20 61 72 65 20 75 6e 61 62 6c  f they are unabl
26d80 65 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20  e to.**         
26d90 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
26da0 20 74 6f 20 68 6f 6c 64 20 74 68 65 69 72 20 6e   to hold their n
26db0 6f 72 6d 61 6c 20 72 65 74 75 72 6e 20 73 74 72  ormal return str
26dc0 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33  ings..**.** {H13
26dd0 37 32 35 7d 20 49 66 20 74 68 65 20 4e 20 70 61  725} If the N pa
26de0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
26df0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
26e00 53 2c 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20  S,N)] or.**     
26e10 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f       [sqlite3_co
26e20 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  lumn_name16(S,N)
26e30 5d 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  ] is out of rang
26e40 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20  e, then the.**  
26e50 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
26e60 65 73 20 72 65 74 75 72 6e 20 61 20 4e 55 4c 4c  es return a NULL
26e70 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
26e80 7b 48 31 33 37 32 36 7d 20 54 68 65 20 73 74 72  {H13726} The str
26e90 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
26ea0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
26eb0 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 61 6e 64 0a  _name(S,N)] and.
26ec0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
26ed0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
26ee0 31 36 28 53 2c 4e 29 5d 20 61 72 65 20 76 61 6c  16(S,N)] are val
26ef0 69 64 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  id until the nex
26f00 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 61  t.**          ca
26f10 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 72 6f 75  ll to either rou
26f20 74 69 6e 65 20 77 69 74 68 20 74 68 65 20 73 61  tine with the sa
26f30 6d 65 20 53 20 61 6e 64 20 4e 20 70 61 72 61 6d  me S and N param
26f40 65 74 65 72 73 0a 2a 2a 20 20 20 20 20 20 20 20  eters.**        
26f50 20 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69    or until [sqli
26f60 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 5d  te3_finalize(S)]
26f70 20 69 73 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a   is called..**.*
26f80 2a 20 7b 48 31 33 37 32 37 7d 20 57 68 65 6e 20  * {H13727} When 
26f90 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
26fa0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
26fb0 61 74 65 6d 65 6e 74 20 63 6f 6e 74 61 69 6e 73  atement contains
26fc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20  .**          an 
26fd0 41 53 20 63 6c 61 75 73 65 2c 20 74 68 65 20 6e  AS clause, the n
26fe0 61 6d 65 20 6f 66 20 74 68 61 74 20 63 6f 6c 75  ame of that colu
26ff0 6d 6e 20 69 73 20 74 68 65 20 69 64 65 6e 74 69  mn is the identi
27000 66 69 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20  fier.**         
27010 20 74 6f 20 74 68 65 20 72 69 67 68 74 20 6f 66   to the right of
27020 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64 2e   the AS keyword.
27030 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
27040 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
27050 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
27060 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
27070 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
27080 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
27090 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
270a0 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
270b0 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
270c0 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
270d0 65 73 75 6c 74 20 7b 48 31 33 37 34 30 7d 20 3c  esult {H13740} <
270e0 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S10700>.**.** Th
270f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
27100 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
27110 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63  determine what c
27120 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a  olumn of what.**
27130 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20   table in which 
27140 64 61 74 61 62 61 73 65 20 61 20 72 65 73 75 6c  database a resul
27150 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
27160 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20  statement comes 
27170 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e 61 6d  from..** The nam
27180 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
27190 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
271a0 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
271b0 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
271c0 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
271d0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68 65  -16 string.  The
271e0 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
271f0 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
27200 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
27210 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
27220 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
27230 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
27240 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
27250 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
27260 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
27270 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65  ..** The returne
27280 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69  d string is vali
27290 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65  d until the [pre
272a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
272b0 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a   is destroyed.**
272c0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
272d0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
272e0 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
272f0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
27300 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
27310 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
27320 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  ncoding..**.** T
27330 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
27340 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
27350 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
27360 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
27370 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
27380 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
27390 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
273a0 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c 6c 6f  ent to the follo
273b0 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20 61 20  wing calls is a 
273c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
273d0 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65 20 66  ent]..** These f
273e0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
273f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
27400 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  t the Nth column
27410 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
27420 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
27430 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
27440 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
27450 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  gument..**.** If
27460 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
27470 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
27480 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
27490 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a  expression or.**
274a0 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
274b0 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
274c0 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
274d0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
274e0 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e   return.** NULL.
274f0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20    These routine 
27500 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
27510 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
27520 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
27530 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
27540 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
27550 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
27560 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
27570 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 0a  database, table.
27580 2a 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 74 68  ** and column th
27590 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
275a0 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
275b0 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
275c0 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68   As with all oth
275d0 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
275e0 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65 64 20  those postfixed 
275f0 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
27600 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
27610 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68 65 20  ed strings, the 
27620 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
27630 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 20 7b 45  return UTF-8. {E
27640 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ND}.**.** These 
27650 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
27660 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
27670 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
27680 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
27690 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
276a0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
276b0 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
276c0 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a  ymbol defined..*
276d0 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 0a 2a 2a  *.** {A13751}.**
276e0 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
276f0 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
27700 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
27710 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
27720 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
27730 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27740 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
27750 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
27760 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
27770 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
27780 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54  .**.** INVARIANT
27790 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 31  S:.**.** {H13741
277a0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
277b0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
277c0 61 6d 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  ame(S,N)] interf
277d0 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
277e0 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
277f0 68 65 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  he UTF-8 zero-te
27800 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66  rminated name of
27810 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
27820 6f 6d 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  om which the.** 
27830 20 20 20 20 20 20 20 20 20 4e 74 68 20 72 65 73           Nth res
27840 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ult column of th
27850 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
27860 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74 72  ement] S is extr
27870 61 63 74 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20  acted,.**       
27880 20 20 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68     or NULL if th
27890 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
278a0 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65  S is a general e
278b0 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20  xpression.**    
278c0 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62        or if unab
278d0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
278e0 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74  emory to store t
278f0 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b  he name..**.** {
27900 48 31 33 37 34 32 7d 20 54 68 65 20 5b 73 71 6c  H13742} The [sql
27910 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
27920 62 61 73 65 5f 6e 61 6d 65 31 36 28 53 2c 4e 29  base_name16(S,N)
27930 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
27940 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20 20 20  rns either.**   
27950 20 20 20 20 20 20 20 74 68 65 20 55 54 46 2d 31         the UTF-1
27960 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
27970 64 65 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  der zero-termina
27980 74 65 64 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  ted name of the 
27990 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20 20  database.**     
279a0 20 20 20 20 20 66 72 6f 6d 20 77 68 69 63 68 20       from which 
279b0 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
279c0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72  olumn of the [pr
279d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
279e0 5d 20 53 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ] S is.**       
279f0 20 20 20 65 78 74 72 61 63 74 65 64 2c 20 6f 72     extracted, or
27a00 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
27a10 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
27a20 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73  a general expres
27a30 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  sion.**         
27a40 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
27a50 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
27a60 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61   to store the na
27a70 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34  me..**.** {H1374
27a80 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  3} The [sqlite3_
27a90 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
27aa0 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  e(S,N)] interfac
27ab0 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
27ac0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
27ad0 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
27ae0 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f 66 20 74  inated name of t
27af0 68 65 20 74 61 62 6c 65 20 66 72 6f 6d 20 77 68  he table from wh
27b00 69 63 68 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ich the.**      
27b10 20 20 20 20 4e 74 68 20 72 65 73 75 6c 74 20 63      Nth result c
27b20 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72  olumn of the [pr
27b30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27b40 5d 20 53 20 69 73 20 65 78 74 72 61 63 74 65 64  ] S is extracted
27b50 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  ,.**          or
27b60 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 4e 74 68   NULL if the Nth
27b70 20 63 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20   column of S is 
27b80 61 20 67 65 6e 65 72 61 6c 20 65 78 70 72 65 73  a general expres
27b90 73 69 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  sion.**         
27ba0 20 6f 72 20 69 66 20 75 6e 61 62 6c 65 20 74 6f   or if unable to
27bb0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
27bc0 20 74 6f 20 73 74 6f 72 65 20 74 68 65 20 6e 61   to store the na
27bd0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34  me..**.** {H1374
27be0 34 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  4} The [sqlite3_
27bf0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
27c00 65 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66  e16(S,N)] interf
27c10 61 63 65 20 72 65 74 75 72 6e 73 20 65 69 74 68  ace returns eith
27c20 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  er.**          t
27c30 68 65 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  he UTF-16 native
27c40 20 62 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f   byte order zero
27c50 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65  -terminated name
27c60 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
27c70 20 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 77            from w
27c80 68 69 63 68 20 74 68 65 20 4e 74 68 20 72 65 73  hich the Nth res
27c90 75 6c 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ult column of th
27ca0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
27cb0 65 6d 65 6e 74 5d 20 53 20 69 73 0a 2a 2a 20 20  ement] S is.**  
27cc0 20 20 20 20 20 20 20 20 65 78 74 72 61 63 74 65          extracte
27cd0 64 2c 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  d, or NULL if th
27ce0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
27cf0 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20 65  S is a general e
27d00 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 20 20 20  xpression.**    
27d10 20 20 20 20 20 20 6f 72 20 69 66 20 75 6e 61 62        or if unab
27d20 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
27d30 65 6d 6f 72 79 20 74 6f 20 73 74 6f 72 65 20 74  emory to store t
27d40 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 7b  he name..**.** {
27d50 48 31 33 37 34 35 7d 20 54 68 65 20 5b 73 71 6c  H13745} The [sql
27d60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
27d70 69 6e 5f 6e 61 6d 65 28 53 2c 4e 29 5d 20 69 6e  in_name(S,N)] in
27d80 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27d90 65 69 74 68 65 72 0a 2a 2a 20 20 20 20 20 20 20  either.**       
27da0 20 20 20 74 68 65 20 55 54 46 2d 38 20 7a 65 72     the UTF-8 zer
27db0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d  o-terminated nam
27dc0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
27dd0 6f 6c 75 6d 6e 20 66 72 6f 6d 20 77 68 69 63 68  olumn from which
27de0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
27df0 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
27e00 6d 6e 20 6f 66 20 74 68 65 20 5b 70 72 65 70 61  mn of the [prepa
27e10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
27e20 20 69 73 20 65 78 74 72 61 63 74 65 64 2c 0a 2a   is extracted,.*
27e30 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20 4e 55  *          or NU
27e40 4c 4c 20 69 66 20 74 68 65 20 4e 74 68 20 63 6f  LL if the Nth co
27e50 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 20 67  lumn of S is a g
27e60 65 6e 65 72 61 6c 20 65 78 70 72 65 73 73 69 6f  eneral expressio
27e70 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  n.**          or
27e80 20 69 66 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   if unable to al
27e90 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
27ea0 20 73 74 6f 72 65 20 74 68 65 20 6e 61 6d 65 2e   store the name.
27eb0 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 34 36 7d 20  .**.** {H13746} 
27ec0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  The [sqlite3_col
27ed0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
27ee0 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63  6(S,N)] interfac
27ef0 65 20 72 65 74 75 72 6e 73 20 65 69 74 68 65 72  e returns either
27f00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65  .**          the
27f10 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
27f20 79 74 65 20 6f 72 64 65 72 20 7a 65 72 6f 2d 74  yte order zero-t
27f30 65 72 6d 69 6e 61 74 65 64 20 6e 61 6d 65 20 6f  erminated name o
27f40 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 20  f the table.**  
27f50 20 20 20 20 20 20 20 20 63 6f 6c 75 6d 6e 20 66          column f
27f60 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 4e 74  rom which the Nt
27f70 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
27f80 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
27f90 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
27fa0 74 65 6d 65 6e 74 5d 20 53 20 69 73 20 65 78 74  tement] S is ext
27fb0 72 61 63 74 65 64 2c 20 6f 72 20 4e 55 4c 4c 20  racted, or NULL 
27fc0 69 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  if the Nth colum
27fd0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66  n.**          of
27fe0 20 53 20 69 73 20 61 20 67 65 6e 65 72 61 6c 20   S is a general 
27ff0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 69 66  expression or if
28000 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
28010 61 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20  ate memory.**   
28020 20 20 20 20 20 20 20 74 6f 20 73 74 6f 72 65 20         to store 
28030 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  the name..**.** 
28040 7b 48 31 33 37 34 38 7d 20 54 68 65 20 72 65 74  {H13748} The ret
28050 75 72 6e 20 76 61 6c 75 65 73 20 66 72 6f 6d 0a  urn values from.
28060 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
28070 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
28080 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
28090 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
280a0 72 66 61 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20  rfaces].**      
280b0 20 20 20 20 61 72 65 20 76 61 6c 69 64 20 66 6f      are valid fo
280c0 72 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  r the lifetime o
280d0 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
280e0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20  statement].**   
280f0 20 20 20 20 20 20 20 6f 72 20 75 6e 74 69 6c 20         or until 
28100 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
28110 63 68 61 6e 67 65 64 20 62 79 20 61 6e 6f 74 68  changed by anoth
28120 65 72 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20  er metadata.**  
28130 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63          interfac
28140 65 20 63 61 6c 6c 20 66 6f 72 20 74 68 65 20 73  e call for the s
28150 61 6d 65 20 70 72 65 70 61 72 65 64 20 73 74 61  ame prepared sta
28160 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
28170 6e 2e 0a 2a 2a 0a 2a 2a 20 41 53 53 55 4d 50 54  n..**.** ASSUMPT
28180 49 4f 4e 53 3a 0a 2a 2a 0a 2a 2a 20 7b 41 31 33  IONS:.**.** {A13
28190 37 35 31 7d 20 49 66 20 74 77 6f 20 6f 72 20 6d  751} If two or m
281a0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
281b0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
281c0 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
281d0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
281e0 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
281f0 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
28200 63 65 73 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ces].**         
28210 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
28220 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28230 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
28240 6c 75 6d 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  lumn.**         
28250 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
28260 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
28270 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
28280 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
28290 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
282a0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
282b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
282c0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
282d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
282e0 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
282f0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
28300 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
28310 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
28320 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
28330 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
28340 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
28350 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
28360 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
28370 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
28380 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
28390 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
283a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
283b0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
283c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
283d0 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
283e0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
283f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28400 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
28410 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
28420 75 6c 74 20 7b 48 31 33 37 36 30 7d 20 3c 53 31  ult {H13760} <S1
28430 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0700>.**.** The 
28440 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
28450 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
28460 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
28470 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
28480 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
28490 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
284a0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
284b0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
284c0 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
284d0 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
284e0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
284f0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
28500 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
28510 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
28520 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
28530 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
28540 72 65 74 75 72 6e 65 64 2e 20 20 49 66 20 74 68  returned.  If th
28550 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
28560 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69  the result set i
28570 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  s an.** expressi
28580 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20  on or subquery, 
28590 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  then a NULL poin
285a0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
285b0 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64  .** The returned
285c0 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
285d0 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
285e0 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72   {END}.**.** For
285f0 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
28600 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
28610 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
28620 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
28630 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
28640 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
28650 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
28660 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
28670 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
28680 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
28690 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
286a0 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
286b0 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
286c0 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
286d0 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
286e0 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
286f0 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
28700 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
28710 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a  column (i==0)..*
28720 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
28730 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
28740 65 20 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75  e typing.  So ju
28750 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
28760 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
28770 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
28780 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
28790 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
287a0 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
287b0 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
287c0 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
287d0 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
287e0 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
287f0 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
28800 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
28810 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
28820 2e 20 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73  .  Type.** is as
28830 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
28840 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
28850 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
28860 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
28870 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
28880 61 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  alues..**.** INV
28890 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
288a0 48 31 33 37 36 31 7d 20 20 41 20 73 75 63 63 65  H13761}  A succe
288b0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
288c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
288d0 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20 72 65 74  cltype(S,N)] ret
288e0 75 72 6e 73 20 61 0a 2a 2a 20 20 20 20 20 20 20  urns a.**       
288f0 20 20 20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61      zero-termina
28900 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
28910 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
28920 64 65 63 6c 61 72 65 64 20 64 61 74 61 74 79 70  declared datatyp
28930 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6f  e.**           o
28940 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
28950 6d 6e 20 74 68 61 74 20 61 70 70 65 61 72 73 20  mn that appears 
28960 61 73 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  as the Nth colum
28970 6e 20 28 6e 75 6d 62 65 72 65 64 0a 2a 2a 20 20  n (numbered.**  
28980 20 20 20 20 20 20 20 20 20 66 72 6f 6d 20 30 29           from 0)
28990 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
289a0 65 74 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  et to the [prepa
289b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
289c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 36 32 7d  ..**.** {H13762}
289d0 20 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63    A successful c
289e0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
289f0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
28a00 36 28 53 2c 4e 29 5d 0a 2a 2a 20 20 20 20 20 20  6(S,N)].**      
28a10 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20 7a       returns a z
28a20 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
28a30 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
28a40 65 20 6f 72 64 65 72 20 73 74 72 69 6e 67 0a 2a  e order string.*
28a50 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74  *           cont
28a60 61 69 6e 69 6e 67 20 74 68 65 20 64 65 63 6c 61  aining the decla
28a70 72 65 64 20 64 61 74 61 74 79 70 65 20 6f 66 20  red datatype of 
28a80 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
28a90 20 74 68 61 74 20 61 70 70 65 61 72 73 0a 2a 2a   that appears.**
28aa0 20 20 20 20 20 20 20 20 20 20 20 61 73 20 74 68             as th
28ab0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 28 6e 75  e Nth column (nu
28ac0 6d 62 65 72 65 64 20 66 72 6f 6d 20 30 29 20 6f  mbered from 0) o
28ad0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
28ae0 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   to the.**      
28af0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
28b00 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a  tatement] S..**.
28b10 2a 2a 20 7b 48 31 33 37 36 33 7d 20 20 49 66 20  ** {H13763}  If 
28b20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 30  N is less than 0
28b30 20 6f 72 20 4e 20 69 73 20 67 72 65 61 74 65 72   or N is greater
28b40 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
28b50 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74  o.**           t
28b60 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
28b70 75 6d 6e 73 20 69 6e 20 74 68 65 20 5b 70 72 65  umns in the [pre
28b80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28b90 20 53 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   S,.**          
28ba0 20 6f 72 20 69 66 20 74 68 65 20 4e 74 68 20 63   or if the Nth c
28bb0 6f 6c 75 6d 6e 20 6f 66 20 53 20 69 73 20 61 6e  olumn of S is an
28bc0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
28bd0 75 62 71 75 65 72 79 20 72 61 74 68 65 72 0a 2a  ubquery rather.*
28be0 2a 20 20 20 20 20 20 20 20 20 20 20 74 68 61 6e  *           than
28bf0 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 2c   a table column,
28c00 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20   or if a memory 
28c10 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
28c20 72 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  re.**           
28c30 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 65 6e  occurs during en
28c40 63 6f 64 69 6e 67 20 63 6f 6e 76 65 72 73 69 6f  coding conversio
28c50 6e 73 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  ns, then.**     
28c60 20 20 20 20 20 20 63 61 6c 6c 73 20 74 6f 20 5b        calls to [
28c70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
28c80 65 63 6c 74 79 70 65 28 53 2c 4e 29 5d 20 6f 72  ecltype(S,N)] or
28c90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 5b 73  .**           [s
28ca0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
28cb0 63 6c 74 79 70 65 31 36 28 53 2c 4e 29 5d 20 72  cltype16(S,N)] r
28cc0 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2f 0a 63  eturn NULL..*/.c
28cd0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
28ce0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
28cf0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
28d00 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
28d10 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
28d20 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
28d30 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
28d40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28d50 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51  : Evaluate An SQ
28d60 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33  L Statement {H13
28d70 32 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a  200} <S10000>.**
28d80 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
28d90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28da0 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
28db0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a  ed using either.
28dc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
28dd0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
28de0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
28df0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
28e00 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
28e10 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
28e20 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
28e30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28e40 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
28e50 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
28e60 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
28e70 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
28e80 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
28e90 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
28ea0 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
28eb0 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
28ec0 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
28ed0 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
28ee0 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
28ef0 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
28f00 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
28f10 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
28f20 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
28f30 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
28f40 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
28f50 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
28f60 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
28f70 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
28f80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
28f90 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
28fa0 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
28fb0 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
28fc0 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
28fd0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
28fe0 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
28ff0 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
29000 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
29010 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
29020 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
29030 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 6c 65  .**.** In the le
29040 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
29050 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
29060 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
29070 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
29080 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
29090 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
290a0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
290b0 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
290c0 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 22  ]..** With the "
290d0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
290e0 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
290f0 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
29100 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
29110 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
29120 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
29130 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53  s well..**.** [S
29140 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
29150 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
29160 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
29170 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
29180 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
29190 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
291a0 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
291b0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
291c0 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a   is a [COMMIT].*
291d0 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
291e0 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
291f0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
29200 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
29210 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
29220 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
29230 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
29240 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63  [COMMIT] and occ
29250 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20  urs within a.** 
29260 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
29270 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68  tion then you sh
29280 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68  ould rollback th
29290 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
292a0 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69  fore.** continui
292b0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ng..**.** [SQLIT
292c0 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
292d0 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
292e0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
292f0 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
29300 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
29310 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
29320 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
29330 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
29340 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
29350 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
29360 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
29370 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
29380 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
29390 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
293a0 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
293b0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
293c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
293d0 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
293e0 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
293f0 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a  en [SQLITE_ROW].
29400 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  ** is returned e
29410 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
29420 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
29430 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69  ady for processi
29440 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ng by the.** cal
29450 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
29460 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
29470 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d  using the [colum
29480 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
29490 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
294a0 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
294b0 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
294c0 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
294d0 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b  of data..**.** [
294e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
294f0 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
29500 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
29510 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
29520 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
29530 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
29540 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
29550 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
29560 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
29570 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
29580 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
29590 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
295a0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
295b0 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20 6c 65  ..** With the le
295c0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
295d0 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
295e0 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
295f0 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
29600 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
29610 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
29620 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
29630 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
29640 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
29650 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
29660 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
29670 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
29680 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
29690 20 20 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e    In the "v2" in
296a0 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
296b0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
296c0 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
296d0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
296e0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
296f0 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
29700 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
29710 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
29720 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
29730 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
29740 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
29750 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
29760 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29770 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
29780 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
29790 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
297a0 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
297b0 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
297c0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
297d0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
297e0 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
297f0 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
29800 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
29810 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
29820 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29830 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
29840 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
29850 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
29860 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
29870 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e   time..**.** <b>
29880 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
29890 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
298a0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
298b0 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
298c0 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
298d0 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
298e0 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
298f0 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
29900 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
29910 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
29920 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
29930 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
29940 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
29950 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
29960 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
29970 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
29980 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
29990 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
299a0 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
299b0 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
299c0 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
299d0 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
299e0 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
299f0 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
29a00 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
29a10 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
29a20 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
29a30 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
29a40 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
29a50 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
29a60 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
29a70 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
29a80 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
29a90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29aa0 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
29ab0 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
29ac0 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
29ad0 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
29ae0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
29af0 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
29b00 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
29b10 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
29b20 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
29b30 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
29b40 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
29b50 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
29b60 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
29b70 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
29b80 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
29b90 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 32 30 32 7d  :.**.** {H13202}
29ba0 20 20 49 66 20 74 68 65 20 5b 70 72 65 70 61 72    If the [prepar
29bb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
29bc0 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  is ready to be r
29bd0 75 6e 2c 20 74 68 65 6e 0a 2a 2a 20 20 20 20 20  un, then.**     
29be0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 73        [sqlite3_s
29bf0 74 65 70 28 53 29 5d 20 61 64 76 61 6e 63 65 73  tep(S)] advances
29c00 20 74 68 61 74 20 70 72 65 70 61 72 65 64 20 73   that prepared s
29c10 74 61 74 65 6d 65 6e 74 20 75 6e 74 69 6c 0a 2a  tatement until.*
29c20 2a 20 20 20 20 20 20 20 20 20 20 20 63 6f 6d 70  *           comp
29c30 6c 65 74 69 6f 6e 20 6f 72 20 75 6e 74 69 6c 20  letion or until 
29c40 69 74 20 69 73 20 72 65 61 64 79 20 74 6f 20 72  it is ready to r
29c50 65 74 75 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f  eturn another ro
29c60 77 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20  w of the.**     
29c70 20 20 20 20 20 20 72 65 73 75 6c 74 20 73 65 74        result set
29c80 2c 20 6f 72 20 75 6e 74 69 6c 20 61 6e 20 5b 73  , or until an [s
29c90 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
29ca0 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 0a 2a 2a   | interrupt].**
29cb0 20 20 20 20 20 20 20 20 20 20 20 6f 72 20 61 20             or a 
29cc0 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 6f  run-time error o
29cd0 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  ccurs..**.** {H1
29ce0 35 33 30 34 7d 20 20 57 68 65 6e 20 61 20 63 61  5304}  When a ca
29cf0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
29d00 74 65 70 28 53 29 5d 20 63 61 75 73 65 73 20 74  tep(S)] causes t
29d10 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
29d20 74 65 6d 65 6e 74 5d 0a 2a 2a 20 20 20 20 20 20  tement].**      
29d30 20 20 20 20 20 53 20 74 6f 20 72 75 6e 20 74 6f       S to run to
29d40 20 63 6f 6d 70 6c 65 74 69 6f 6e 2c 20 74 68 65   completion, the
29d50 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
29d60 73 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  s [SQLITE_DONE].
29d70 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 33 30 36 7d 20  .**.** {H15306} 
29d80 20 57 68 65 6e 20 61 20 63 61 6c 6c 20 74 6f 20   When a call to 
29d90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
29da0 5d 20 73 74 6f 70 73 20 62 65 63 61 75 73 65 20  ] stops because 
29db0 69 74 20 69 73 20 72 65 61 64 79 20 74 6f 0a 2a  it is ready to.*
29dc0 2a 20 20 20 20 20 20 20 20 20 20 20 72 65 74 75  *           retu
29dd0 72 6e 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 6f  rn another row o
29de0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
29df0 2c 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51  , it returns [SQ
29e00 4c 49 54 45 5f 52 4f 57 5d 2e 0a 2a 2a 0a 2a 2a  LITE_ROW]..**.**
29e10 20 7b 48 31 35 33 30 38 7d 20 20 49 66 20 61 20   {H15308}  If a 
29e20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
29e30 5f 73 74 65 70 28 53 29 5d 20 65 6e 63 6f 75 6e  _step(S)] encoun
29e40 74 65 72 73 20 61 6e 0a 2a 2a 20 20 20 20 20 20  ters an.**      
29e50 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 69 6e       [sqlite3_in
29e60 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72 72  terrupt | interr
29e70 75 70 74 5d 20 6f 72 20 61 20 72 75 6e 2d 74 69  upt] or a run-ti
29e80 6d 65 20 65 72 72 6f 72 2c 0a 2a 2a 20 20 20 20  me error,.**    
29e90 20 20 20 20 20 20 20 69 74 20 72 65 74 75 72 6e         it return
29ea0 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
29eb0 20 65 72 72 6f 72 20 63 6f 64 65 20 74 68 61 74   error code that
29ec0 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 0a 2a   is not one of.*
29ed0 2a 20 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  *           [SQL
29ee0 49 54 45 5f 4f 4b 5d 2c 20 5b 53 51 4c 49 54 45  ITE_OK], [SQLITE
29ef0 5f 52 4f 57 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  _ROW], or [SQLIT
29f00 45 5f 44 4f 4e 45 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  E_DONE]..**.** {
29f10 48 31 35 33 31 30 7d 20 20 49 66 20 61 6e 20 5b  H15310}  If an [
29f20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
29f30 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 20 6f  t | interrupt] o
29f40 72 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  r a run-time err
29f50 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  or.**           
29f60 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 61 20  occurs during a 
29f70 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
29f80 5f 73 74 65 70 28 53 29 5d 0a 2a 2a 20 20 20 20  _step(S)].**    
29f90 20 20 20 20 20 20 20 66 6f 72 20 61 20 5b 70 72         for a [pr
29fa0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29fb0 5d 20 53 20 63 72 65 61 74 65 64 20 75 73 69 6e  ] S created usin
29fc0 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 6c  g.**           l
29fd0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 73  egacy interfaces
29fe0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29ff0 65 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20  e()] or.**      
2a000 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 70 72       [sqlite3_pr
2a010 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 65 6e  epare16()], then
2a020 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 72 65   the function re
2a030 74 75 72 6e 73 20 65 69 74 68 65 72 0a 2a 2a 20  turns either.** 
2a040 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54            [SQLIT
2a050 45 5f 45 52 52 4f 52 5d 2c 20 5b 53 51 4c 49 54  E_ERROR], [SQLIT
2a060 45 5f 42 55 53 59 5d 2c 20 6f 72 20 5b 53 51 4c  E_BUSY], or [SQL
2a070 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2f 0a  ITE_MISUSE]..*/.
2a080 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
2a090 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2a0a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a0b0 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
2a0c0 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
2a0d0 73 65 74 20 7b 48 31 33 37 37 30 7d 20 3c 53 31  set {H13770} <S1
2a0e0 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75  0700>.**.** Retu
2a0f0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2a100 66 20 76 61 6c 75 65 73 20 69 6e 20 74 68 65 20  f values in the 
2a110 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
2a120 68 65 20 72 65 73 75 6c 74 20 73 65 74 2e 0a 2a  he result set..*
2a130 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
2a140 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 37 31 7d 20  .**.** {H13771} 
2a150 20 41 66 74 65 72 20 61 20 63 61 6c 6c 20 74 6f   After a call to
2a160 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2a170 29 5d 20 74 68 61 74 20 72 65 74 75 72 6e 73 20  )] that returns 
2a180 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 0a 2a 2a  [SQLITE_ROW],.**
2a190 20 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b             the [
2a1a0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2a1b0 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e 65 20 77  nt(S)] routine w
2a1c0 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 73  ill return the s
2a1d0 61 6d 65 20 76 61 6c 75 65 0a 2a 2a 20 20 20 20  ame value.**    
2a1e0 20 20 20 20 20 20 20 61 73 20 74 68 65 20 5b 73         as the [s
2a1f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2a200 75 6e 74 28 53 29 5d 20 66 75 6e 63 74 69 6f 6e  unt(S)] function
2a210 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 37 37 32 7d  ..**.** {H13772}
2a220 20 20 41 66 74 65 72 20 5b 73 71 6c 69 74 65 33    After [sqlite3
2a230 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 72 65  _step(S)] has re
2a240 74 75 72 6e 65 64 20 61 6e 79 20 76 61 6c 75 65  turned any value
2a250 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a 2a 20 20   other than.**  
2a260 20 20 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45           [SQLITE
2a270 5f 52 4f 57 5d 20 6f 72 20 62 65 66 6f 72 65 20  _ROW] or before 
2a280 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2a290 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
2a2a0 64 20 6f 6e 20 74 68 65 0a 2a 2a 20 20 20 20 20  d on the.**     
2a2b0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
2a2c0 73 74 61 74 65 6d 65 6e 74 5d 20 66 6f 72 20 74  statement] for t
2a2d0 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 69  he first time si
2a2e0 6e 63 65 20 69 74 20 77 61 73 0a 2a 2a 20 20 20  nce it was.**   
2a2f0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2a300 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
2a310 72 65 64 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  red] or [sqlite3
2a320 5f 72 65 73 65 74 20 7c 20 72 65 73 65 74 5d 2c  _reset | reset],
2a330 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 74 68  .**           th
2a340 65 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  e [sqlite3_data_
2a350 63 6f 75 6e 74 28 53 29 5d 20 72 6f 75 74 69 6e  count(S)] routin
2a360 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  e returns zero..
2a370 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
2a380 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
2a390 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2a3a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a3b0 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
2a3c0 61 74 79 70 65 73 20 7b 48 31 30 32 36 35 7d 20  atypes {H10265} 
2a3d0 3c 53 31 30 31 31 30 3e 3c 53 31 30 31 32 30 3e  <S10110><S10120>
2a3e0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
2a3f0 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
2a400 7b 48 31 30 32 36 36 7d 20 45 76 65 72 79 20 76  {H10266} Every v
2a410 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
2a420 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
2a430 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
2a440 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
2a450 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
2a460 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
2a470 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
2a480 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
2a490 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
2a4a0 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
2a4b0 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
2a4c0 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d  L.** </ul> {END}
2a4d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2a4e0 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
2a4f0 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
2a500 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
2a510 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
2a520 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
2a530 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
2a540 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
2a550 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
2a560 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
2a570 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
2a580 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
2a590 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
2a5a0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2a5b0 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
2a5c0 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
2a5d0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20  e SQLITE3_TEXT, 
2a5e0 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
2a5f0 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
2a600 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
2a610 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a620 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
2a630 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
2a640 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
2a650 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
2a660 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
2a670 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
2a680 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
2a690 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
2a6a0 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
2a6b0 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
2a6c0 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
2a6d0 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
2a6e0 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
2a6f0 75 65 72 79 20 7b 48 31 33 38 30 30 7d 20 3c 53  uery {H13800} <S
2a700 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  10700>.** KEYWOR
2a710 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
2a720 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
2a730 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
2a740 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73  es form the "res
2a750 75 6c 74 20 73 65 74 20 71 75 65 72 79 22 20 69  ult set query" i
2a760 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2a770 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2a780 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2a790 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
2a7a0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
2a7b0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
2a7c0 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
2a7d0 20 20 49 6e 20 65 76 65 72 79 20 63 61 73 65 20    In every case 
2a7e0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2a7f0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a  nt is a pointer.
2a800 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  ** to the [prepa
2a810 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2a820 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61  hat is being eva
2a830 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c  luated (the [sql
2a840 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74  ite3_stmt*].** t
2a850 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
2a860 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70   from [sqlite3_p
2a870 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2a880 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
2a890 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  nts).** and the 
2a8a0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2a8b0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
2a8c0 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
2a8d0 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
2a8e0 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
2a8f0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65 66  turned.  The lef
2a900 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  tmost column of 
2a910 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68  the result set h
2a920 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a  as the index 0..
2a930 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
2a940 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
2a950 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
2a960 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
2a970 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
2a980 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
2a990 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
2a9a0 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
2a9b0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65  efined..** These
2a9c0 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
2a9d0 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
2a9e0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
2a9f0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
2aa00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2aa10 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
2aa20 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
2aa30 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
2aa40 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
2aa50 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2aa60 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  ] have been call
2aa70 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ed subsequently.
2aa80 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
2aa90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2aaa0 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
2aab0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2aac0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
2aad0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
2aae0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
2aaf0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
2ab00 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
2ab10 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2ab20 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
2ab30 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2ab40 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
2ab50 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
2ab60 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2ab70 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2ab80 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
2ab90 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
2aba0 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
2abb0 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
2abc0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
2abd0 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
2abe0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2abf0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
2ac00 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2ac10 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
2ac20 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
2ac30 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
2ac40 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
2ac50 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
2ac60 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
2ac70 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
2ac80 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65  mn.  The returne
2ac90 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
2aca0 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
2acb0 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
2acc0 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
2acd0 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
2ace0 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
2acf0 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
2ad00 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
2ad10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ad20 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
2ad30 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
2ad40 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
2ad50 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
2ad60 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
2ad70 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
2ad80 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
2ad90 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
2ada0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2adb0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2adc0 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
2add0 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
2ade0 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
2adf0 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
2ae00 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
2ae10 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
2ae20 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
2ae30 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
2ae40 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20  * If the result 
2ae50 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
2ae60 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  -8 string then t
2ae70 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2ae80 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75  n_bytes().** rou
2ae90 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2aea0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2aeb0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
2aec0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20 74   string..** If t
2aed0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2aee0 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
2aef0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2af00 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
2af10 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2af20 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
2af30 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2af40 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2af50 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
2af60 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
2af70 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
2af80 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2af90 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
2afa0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
2afb0 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
2afc0 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
2afd0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2afe0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2aff0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2b000 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 76  string..** The v
2b010 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64 6f  alue returned do
2b020 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  es not include t
2b030 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
2b040 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  or at the end.**
2b050 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
2b060 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68   For clarity: th
2b070 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
2b080 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
2b090 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
2b0a0 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
2b0b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
2b0c0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53 74  acters..**.** St
2b0d0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
2b0e0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2b0f0 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
2b100 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2b110 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
2b120 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
2b130 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d  always zero term
2b140 69 6e 61 74 65 64 2e 20 20 54 68 65 20 72 65 74  inated.  The ret
2b150 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
2b160 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
2b170 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
2b180 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
2b190 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a  s an arbitrary.*
2b1a0 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69  * pointer, possi
2b1b0 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20  bly even a NULL 
2b1c0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
2b1d0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2b1e0 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75 74  n_bytes16() rout
2b1f0 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
2b200 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2b210 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20  _bytes().** but 
2b220 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 75 6c  leaves the resul
2b230 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e  t in UTF-16 in n
2b240 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2b250 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d   instead of UTF-
2b260 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20 74  8..** The zero t
2b270 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74  erminator is not
2b280 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69   included in thi
2b290 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  s count..**.** T
2b2a0 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
2b2b0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2b2c0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2b2d0 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
2b2e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2b2f0 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
2b300 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2b310 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2b320 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
2b330 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
2b340 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
2b350 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
2b360 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
2b370 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
2b380 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2b390 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
2b3a0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
2b3b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2b3c0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
2b3d0 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
2b3e0 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
2b3f0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
2b400 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2b410 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
2b420 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2b430 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
2b440 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
2b450 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2b460 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
2b470 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2b480 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
2b490 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2b4a0 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
2b4b0 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ate.  For.** exa
2b4c0 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74  mple, if the int
2b4d0 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
2b4e0 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e  tion is FLOAT an
2b4f0 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a  d a text result.
2b500 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c  ** is requested,
2b510 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2b520 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  tf()] is used in
2b530 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66  ternally to perf
2b540 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65  orm the.** conve
2b550 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61  rsion automatica
2b560 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77  lly.  The follow
2b570 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
2b580 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
2b590 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
2b5a0 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
2b5b0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
2b5c0 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
2b5d0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
2b5e0 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
2b5f0 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
2b600 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
2b610 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
2b620 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2b630 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2b640 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
2b650 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2b660 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2b670 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2b680 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
2b690 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
2b6a0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
2b6b0 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  ult is NULL poin
2b6c0 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
2b6d0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
2b6e0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73  BLOB    <td> Res
2b6f0 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  ult is NULL poin
2b700 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
2b710 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
2b720 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
2b730 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
2b740 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
2b750 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2b760 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2b770 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
2b780 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
2b790 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
2b7a0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
2b7b0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
2b7c0 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58   as INTEGER->TEX
2b7d0 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
2b7e0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
2b7f0 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
2b800 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f  rt from float to
2b810 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
2b820 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2b830 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2b840 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
2b850 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a  g of the float.*
2b860 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2b870 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  T   <td>   BLOB 
2b880 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
2b890 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c  FLOAT->TEXT.** <
2b8a0 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2b8b0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2b8c0 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a  <td> Use atoi().
2b8d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
2b8e0 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  T    <td>  FLOAT
2b8f0 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f      <td> Use ato
2b900 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
2b910 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20   TEXT    <td>   
2b920 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20  BLOB    <td> No 
2b930 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74  change.** <tr><t
2b940 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2b950 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2b960 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
2b970 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a  then use atoi().
2b980 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
2b990 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
2b9a0 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
2b9b0 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
2b9c0 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
2b9d0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2b9e0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2b9f0 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72  > Add a zero ter
2ba00 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65  minator if neede
2ba10 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  d.** </table>.**
2ba20 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a   </blockquote>.*
2ba30 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61  *.** The table a
2ba40 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72  bove makes refer
2ba50 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64  ence to standard
2ba60 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74   C library funct
2ba70 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61  ions atoi().** a
2ba80 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69  nd atof().  SQLi
2ba90 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c  te does not real
2baa0 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e  ly use these fun
2bab0 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20  ctions.  It has 
2bac0 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76  its.** own equiv
2bad0 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72  alent internal r
2bae0 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74  outines.  The at
2baf0 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20  oi() and atof() 
2bb00 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65  names are.** use
2bb10 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66  d in the table f
2bb20 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62  or brevity and b
2bb30 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20  ecause they are 
2bb40 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74  familiar to most
2bb50 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72  .** C programmer
2bb60 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
2bb70 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
2bb80 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
2bb90 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2bba0 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
2bbb0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2bbc0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
2bbd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2bbe0 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
2bbf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2bc00 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
2bc10 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
2bc20 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
2bc30 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
2bc40 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
2bc50 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
2bc60 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
2bc70 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2bc80 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2bc90 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
2bca0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2bcb0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
2bcc0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2bcd0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2bce0 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
2bcf0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
2bd00 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
2bd10 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
2bd20 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
2bd30 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
2bd40 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
2bd50 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
2bd60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2bd70 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
2bd80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bd90 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2bda0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
2bdb0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
2bdc0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
2bdd0 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
2bde0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2bdf0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
2be00 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2be10 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2be20 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2be30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2be40 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
2be50 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
2be60 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
2be70 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
2be80 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
2be90 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65  * Conversions be
2bea0 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61  tween UTF-16be a
2beb0 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20  nd UTF-16le are 
2bec0 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70  always done in p
2bed0 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e  lace and do.** n
2bee0 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20  ot invalidate a 
2bef0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74  prior pointer, t
2bf00 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
2bf10 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2bf20 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  he buffer.** tha
2bf30 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
2bf40 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77 69  ter points to wi
2bf50 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
2bf60 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
2bf70 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
2bf80 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
2bf90 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
2bfa0 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
2bfb0 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a  sometimes they.*
2bfc0 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62  * are not possib
2bfd0 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
2bfe0 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
2bff0 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
2c000 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
2c010 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65  safest and easie
2c020 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70  st to remember p
2c030 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
2c040 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
2c050 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
2c060 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
2c070 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2c080 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
2c090 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
2c0a0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2c0b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
2c0c0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
2c0d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2c0e0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2c0f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c100 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
2c110 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2c120 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
2c130 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2c140 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
2c150 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
2c160 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
2c170 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
2c180 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
2c190 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
2c1a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2c1b0 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
2c1c0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
2c1d0 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
2c1e0 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
2c1f0 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
2c200 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
2c210 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c220 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
2c230 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c240 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
2c250 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
2c260 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
2c270 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
2c280 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c290 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2c2a0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
2c2b0 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
2c2c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2c2d0 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
2c2e0 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
2c2f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c300 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
2c310 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2c320 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2c330 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
2c340 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
2c350 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
2c360 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
2c370 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
2c380 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
2c390 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
2c3a0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2c3b0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
2c3c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2c3d0 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
2c3e0 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 73  d.  The memory s
2c3f0 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
2c400 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
2c410 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
2c420 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2c430 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61  Do <b>not</b> pa
2c440 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
2c450 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c  returned.** [sql
2c460 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2c470 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
2c480 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
2c490 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
2c4a0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
2c4b0 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79 20 61  ** If a memory a
2c4c0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
2c4d0 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
2c4e0 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
2c4f0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
2c500 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
2c510 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
2c520 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
2c530 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
2c540 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
2c550 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
2c560 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
2c570 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
2c580 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
2c590 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
2c5a0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
2c5b0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
2c5c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
2c5d0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  ]..**.** INVARIA
2c5e0 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38  NTS:.**.** {H138
2c5f0 30 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  03} The [sqlite3
2c600 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c 4e  _column_blob(S,N
2c610 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f 6e  )] interface con
2c620 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20 20  verts the.**    
2c630 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d 6e        Nth column
2c640 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
2c650 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2c660 74 20 73 65 74 20 66 6f 72 0a 2a 2a 20 20 20 20  t set for.**    
2c670 20 20 20 20 20 20 74 68 65 20 5b 70 72 65 70 61        the [prepa
2c680 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2c690 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 61 6e 64   into a BLOB and
2c6a0 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 61 0a   then returns a.
2c6b0 2a 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e  **          poin
2c6c0 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6e 76 65  ter to the conve
2c6d0 72 74 65 64 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  rted value..**.*
2c6e0 2a 20 7b 48 31 33 38 30 36 7d 20 54 68 65 20 5b  * {H13806} The [
2c6f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c700 79 74 65 73 28 53 2c 4e 29 5d 20 69 6e 74 65 72  ytes(S,N)] inter
2c710 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2c720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 75 6d  .**          num
2c730 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2c740 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
2c750 6e 67 20 28 65 78 63 6c 75 73 69 76 65 20 6f 66  ng (exclusive of
2c760 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2c770 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2c780 20 6f 6e 20 74 68 65 20 73 74 72 69 6e 67 29 20   on the string) 
2c790 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
2c7a0 64 20 62 79 20 74 68 65 0a 2a 2a 20 20 20 20 20  d by the.**     
2c7b0 20 20 20 20 20 6d 6f 73 74 20 72 65 63 65 6e 74       most recent
2c7c0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2c7d0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 53 2c  3_column_blob(S,
2c7e0 4e 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  N)] or.**       
2c7f0 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75     [sqlite3_colu
2c800 6d 6e 5f 74 65 78 74 28 53 2c 4e 29 5d 2e 0a 2a  mn_text(S,N)]..*
2c810 2a 0a 2a 2a 20 7b 48 31 33 38 30 39 7d 20 54 68  *.** {H13809} Th
2c820 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2c830 6e 5f 62 79 74 65 73 31 36 28 53 2c 4e 29 5d 20  n_bytes16(S,N)] 
2c840 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2c850 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
2c860 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65    number of byte
2c870 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20  s in the string 
2c880 28 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68  (exclusive of th
2c890 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a 65  e.**          ze
2c8a0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e  ro terminator on
2c8b0 20 74 68 65 20 73 74 72 69 6e 67 29 20 74 68 61   the string) tha
2c8c0 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 62  t was returned b
2c8d0 79 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  y the.**        
2c8e0 20 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61    most recent ca
2c8f0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2c900 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 53 2c 4e  olumn_text16(S,N
2c910 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 33 38 31  )]..**.** {H1381
2c920 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2c930 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 53 2c  column_double(S,
2c940 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  N)] interface co
2c950 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
2c960 20 20 20 20 20 20 20 4e 74 68 20 63 6f 6c 75 6d         Nth colum
2c970 6e 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  n in the current
2c980 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2c990 6c 74 20 73 65 74 20 66 6f 72 20 74 68 65 0a 2a  lt set for the.*
2c9a0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
2c9b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2c9c0 53 20 69 6e 74 6f 20 61 20 66 6c 6f 61 74 69 6e  S into a floatin
2c9d0 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 61 6e  g point value an
2c9e0 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65  d.**          re
2c9f0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  turns a copy of 
2ca00 74 68 61 74 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  that value..**.*
2ca10 2a 20 7b 48 31 33 38 31 35 7d 20 54 68 65 20 5b  * {H13815} The [
2ca20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2ca30 6e 74 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61  nt(S,N)] interfa
2ca40 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a  ce converts the.
2ca50 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74 68 20  **          Nth 
2ca60 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75  column in the cu
2ca70 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2ca80 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f 72 20   result set for 
2ca90 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2caa0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2cab0 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20 36 34  ent] S into a 64
2cac0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2cad0 67 65 72 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20  ger and.**      
2cae0 20 20 20 20 72 65 74 75 72 6e 73 20 74 68 65 20      returns the 
2caf0 6c 6f 77 65 72 20 33 32 20 62 69 74 73 20 6f 66  lower 32 bits of
2cb00 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a   that integer..*
2cb10 2a 0a 2a 2a 20 7b 48 31 33 38 31 38 7d 20 54 68  *.** {H13818} Th
2cb20 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2cb30 6e 5f 69 6e 74 36 34 28 53 2c 4e 29 5d 20 69 6e  n_int64(S,N)] in
2cb40 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
2cb50 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2cb60 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74   Nth column in t
2cb70 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
2cb80 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2cb90 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
2cba0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
2cbb0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f  tatement] S into
2cbc0 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64   a 64-bit signed
2cbd0 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a 2a 20   integer and.** 
2cbe0 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 73           returns
2cbf0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61 74 20   a copy of that 
2cc00 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b  integer..**.** {
2cc10 48 31 33 38 32 31 7d 20 54 68 65 20 5b 73 71 6c  H13821} The [sql
2cc20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2cc30 28 53 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65  (S,N)] interface
2cc40 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a   converts the.**
2cc50 20 20 20 20 20 20 20 20 20 20 4e 74 68 20 63 6f            Nth co
2cc60 6c 75 6d 6e 20 69 6e 20 74 68 65 20 63 75 72 72  lumn in the curr
2cc70 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
2cc80 65 73 75 6c 74 20 73 65 74 20 66 6f 72 0a 2a 2a  esult set for.**
2cc90 20 20 20 20 20 20 20 20 20 20 74 68 65 20 5b 70            the [p
2cca0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ccb0 74 5d 20 53 20 69 6e 74 6f 20 61 20 7a 65 72 6f  t] S into a zero
2ccc0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
2ccd0 38 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  8.**          st
2cce0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2ccf0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2cd00 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
2cd10 20 7b 48 31 33 38 32 34 7d 20 54 68 65 20 5b 73   {H13824} The [s
2cd20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2cd30 78 74 31 36 28 53 2c 4e 29 5d 20 69 6e 74 65 72  xt16(S,N)] inter
2cd40 66 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68  face converts th
2cd50 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4e 74  e.**          Nt
2cd60 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68 65 20  h column in the 
2cd70 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
2cd80 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 66 6f  he result set fo
2cd90 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
2cda0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
2cdb0 65 6d 65 6e 74 5d 20 53 20 69 6e 74 6f 20 61 20  ement] S into a 
2cdc0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
2cdd0 32 2d 62 79 74 65 0a 2a 2a 20 20 20 20 20 20 20  2-byte.**       
2cde0 20 20 20 61 6c 69 67 6e 65 64 20 55 54 46 2d 31     aligned UTF-1
2cdf0 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
2ce00 64 65 72 20 73 74 72 69 6e 67 20 61 6e 64 20 72  der string and r
2ce10 65 74 75 72 6e 73 0a 2a 2a 20 20 20 20 20 20 20  eturns.**       
2ce20 20 20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20     a pointer to 
2ce30 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  that string..**.
2ce40 2a 2a 20 7b 48 31 33 38 32 37 7d 20 54 68 65 20  ** {H13827} The 
2ce50 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2ce60 74 79 70 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  type(S,N)] inter
2ce70 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
2ce80 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20           one of 
2ce90 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b  [SQLITE_NULL], [
2cea0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
2ceb0 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
2cec0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
2ced0 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b  LITE_TEXT], or [
2cee0 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20  SQLITE_BLOB] as 
2cef0 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a  appropriate for.
2cf00 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
2cf10 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
2cf20 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
2cf30 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2cf40 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
2cf50 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2cf60 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2a 0a 2a  atement] S..**.*
2cf70 2a 20 7b 48 31 33 38 33 30 7d 20 54 68 65 20 5b  * {H13830} The [
2cf80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2cf90 61 6c 75 65 28 53 2c 4e 29 5d 20 69 6e 74 65 72  alue(S,N)] inter
2cfa0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 0a 2a  face returns a.*
2cfb0 2a 20 20 20 20 20 20 20 20 20 20 70 6f 69 6e 74  *          point
2cfc0 65 72 20 74 6f 20 61 6e 20 5b 75 6e 70 72 6f 74  er to an [unprot
2cfd0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2cfe0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 20  lue] object for 
2cff0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2d000 4e 74 68 20 63 6f 6c 75 6d 6e 20 69 6e 20 74 68  Nth column in th
2d010 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  e current row of
2d020 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2d030 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
2d040 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2d050 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 63  atement] S..*/.c
2d060 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2d070 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
2d080 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2d090 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
2d0a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d0b0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
2d0c0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
2d0d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d0e0 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
2d0f0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2d100 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
2d110 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
2d120 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2d130 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
2d140 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73  te3_column_int(s
2d150 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2d160 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
2d170 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63  _int64 sqlite3_c
2d180 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69  olumn_int64(sqli
2d190 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2d1a0 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  Col);.const unsi
2d1b0 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
2d1c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73  e3_column_text(s
2d1d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2d1e0 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76  t iCol);.const v
2d1f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2d200 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74  umn_text16(sqlit
2d210 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2d220 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2d230 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
2d240 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2d250 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76  iCol);.sqlite3_v
2d260 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f  alue *sqlite3_co
2d270 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74  lumn_value(sqlit
2d280 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2d290 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
2d2a0 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
2d2b0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2d2c0 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 30  nt Object {H1330
2d2d0 30 7d 20 3c 53 37 30 33 30 30 3e 3c 53 33 30 31  0} <S70300><S301
2d2e0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
2d2f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2d300 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
2d310 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
2d320 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d330 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ent]..** If the 
2d340 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 65 78  statement was ex
2d350 65 63 75 74 65 64 20 73 75 63 63 65 73 73 66 75  ecuted successfu
2d360 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65 63 75  lly or not execu
2d370 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68 65 6e  ted at all, then
2d380 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73  .** SQLITE_OK is
2d390 20 72 65 74 75 72 6e 65 64 2e 20 49 66 20 65 78   returned. If ex
2d3a0 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  ecution of the s
2d3b0 74 61 74 65 6d 65 6e 74 20 66 61 69 6c 65 64 20  tatement failed 
2d3c0 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  then an.** [erro
2d3d0 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65  r code] or [exte
2d3e0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
2d3f0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2d400 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
2d410 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
2d420 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
2d430 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
2d440 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   of the.** [prep
2d450 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2d460 20 20 49 66 20 74 68 65 20 76 69 72 74 75 61 6c    If the virtual
2d470 20 6d 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74   machine has not
2d480 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78  .** completed ex
2d490 65 63 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69  ecution when thi
2d4a0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  s routine is cal
2d4b0 6c 65 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b  led, that is lik
2d4c0 65 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e  e.** encounterin
2d4d0 67 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e  g an error or an
2d4e0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
2d4f0 75 70 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d  upt | interrupt]
2d500 2e 0a 2a 2a 20 49 6e 63 6f 6d 70 6c 65 74 65 20  ..** Incomplete 
2d510 75 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72  updates may be r
2d520 6f 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74  olled back and t
2d530 72 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63  ransactions canc
2d540 65 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69  eled,.** dependi
2d550 6e 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d  ng on the circum
2d560 73 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65  stances, and the
2d570 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
2d580 20 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62   returned will b
2d590 65 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  e [SQLITE_ABORT]
2d5a0 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e  ..**.** INVARIAN
2d5b0 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30  TS:.**.** {H1130
2d5c0 32 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  2} The [sqlite3_
2d5d0 66 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 6e 74  finalize(S)] int
2d5e0 65 72 66 61 63 65 20 64 65 73 74 72 6f 79 73 20  erface destroys 
2d5f0 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
2d600 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d610 65 6e 74 5d 20 53 20 61 6e 64 20 72 65 6c 65 61  ent] S and relea
2d620 73 65 73 20 61 6c 6c 0a 2a 2a 20 20 20 20 20 20  ses all.**      
2d630 20 20 20 20 6d 65 6d 6f 72 79 20 61 6e 64 20 66      memory and f
2d640 69 6c 65 20 72 65 73 6f 75 72 63 65 73 20 68 65  ile resources he
2d650 6c 64 20 62 79 20 74 68 61 74 20 6f 62 6a 65 63  ld by that objec
2d660 74 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 34  t..**.** {H11304
2d670 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  } If the most re
2d680 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2d690 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2d6a0 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  or the.**       
2d6b0 20 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61     [prepared sta
2d6c0 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
2d6d0 65 64 20 61 6e 20 65 72 72 6f 72 2c 0a 2a 2a 20  ed an error,.** 
2d6e0 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73           then [s
2d6f0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2d700 53 29 5d 20 72 65 74 75 72 6e 73 20 74 68 61 74  S)] returns that
2d710 20 73 61 6d 65 20 65 72 72 6f 72 2e 0a 2a 2f 0a   same error..*/.
2d720 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
2d730 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
2d740 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2d750 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2d760 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
2d770 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48  tement Object {H
2d780 31 33 33 33 30 7d 20 3c 53 37 30 33 30 30 3e 0a  13330} <S70300>.
2d790 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2d7a0 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
2d7b0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2d7c0 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65  reset a [prepare
2d7d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2d7e0 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69  object back to i
2d7f0 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
2d800 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
2d810 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 41 6e  -executed..** An
2d820 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
2d830 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
2d840 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
2d850 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
2d860 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2d870 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
2d880 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
2d890 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
2d8a0 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
2d8b0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
2d8c0 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
2d8d0 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
2d8e0 0a 2a 2a 20 7b 48 31 31 33 33 32 7d 20 54 68 65  .** {H11332} The
2d8f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2d900 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
2d910 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
2d920 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
2d930 2a 2a 20 20 20 20 20 20 20 20 20 20 62 61 63 6b  **          back
2d940 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   to the beginnin
2d950 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d  g of its program
2d960 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 34 7d  ..**.** {H11334}
2d970 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   If the most rec
2d980 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
2d990 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
2d9a0 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
2d9b0 20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74    [prepared stat
2d9c0 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
2d9d0 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
2d9e0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
2d9f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72 20  .**          or 
2da00 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
2da10 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
2da20 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
2da30 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20 20 20 20 20  d on S,.**      
2da40 20 20 20 20 74 68 65 6e 20 5b 73 71 6c 69 74 65      then [sqlite
2da50 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
2da60 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
2da70 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 36 7d 20  .**.** {H11336} 
2da80 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2da90 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2daa0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
2dab0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
2dac0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2dad0 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65  ment] S indicate
2dae0 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e  d an error, then
2daf0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
2db00 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2db10 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
2db20 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
2db30 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  de]..**.** {H113
2db40 33 38 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  38} The [sqlite3
2db50 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
2db60 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68  face does not ch
2db70 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a  ange the values.
2db80 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 66 20 61  **          of a
2db90 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
2dba0 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
2dbb0 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
2dbc0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
2dbd0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
2dbe0 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
2dbf0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2dc00 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
2dc10 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
2dc20 4c 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36  L Functions {H16
2dc30 31 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  100} <S20200>.**
2dc40 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
2dc50 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
2dc60 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
2dc70 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
2dc80 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2dc90 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
2dca0 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
2dcb0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2dcc0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
2dcd0 68 65 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f  hese two functio
2dce0 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79  ns (collectively
2dcf0 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74   known as "funct
2dd00 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
2dd10 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75  tines").** are u
2dd20 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66  sed to add SQL f
2dd30 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
2dd40 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64  egates or to red
2dd50 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69  efine the behavi
2dd60 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e  or.** of existin
2dd70 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  g SQL functions 
2dd80 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  or aggregates.  
2dd90 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65  The only differe
2dda0 6e 63 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a  nce between the.
2ddb0 2a 2a 20 74 77 6f 20 69 73 20 74 68 61 74 20 74  ** two is that t
2ddc0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2ddd0 74 65 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66  ter, the name of
2dde0 20 74 68 65 20 28 73 63 61 6c 61 72 29 20 66 75   the (scalar) fu
2ddf0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
2de00 72 65 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64  regate, is encod
2de10 65 64 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20  ed in UTF-8 for 
2de20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2de30 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54  unction() and UT
2de40 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  F-16.** for sqli
2de50 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2de60 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54  ion16()..**.** T
2de70 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2de80 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
2de90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2dea0 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
2deb0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
2dec0 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 49 66  to be added.  If
2ded0 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 61   a single progra
2dee0 6d 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  m uses more than
2def0 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
2df00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65   connection inte
2df10 72 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c  rnally, then SQL
2df20 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
2df30 62 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 64  be added individ
2df40 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68  ually to.** each
2df50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2df60 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
2df70 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2df80 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
2df90 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2dfa0 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f   to be created o
2dfb0 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20  r.** redefined. 
2dfc0 20 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   The length of t
2dfd0 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
2dfe0 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c  ed to 255 bytes,
2dff0 20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a   exclusive of.**
2e000 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
2e010 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74  ator.  Note that
2e020 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68   the name length
2e030 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74   limit is in byt
2e040 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61  es, not.** chara
2e050 63 74 65 72 73 2e 20 20 41 6e 79 20 61 74 74 65  cters.  Any atte
2e060 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
2e070 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
2e080 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
2e090 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53  ill result in [S
2e0a0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65 69  QLITE_ERROR] bei
2e0b0 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
2e0c0 2a 2a 20 54 68 65 20 74 68 69 72 64 20 70 61 72  ** The third par
2e0d0 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
2e0e0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
2e0f0 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
2e100 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2e110 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2e120 65 20 74 61 6b 65 73 2e 20 49 66 20 74 68 69 73  e takes. If this
2e130 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65   parameter is ne
2e140 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
2e150 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2e160 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
2e170 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
2e180 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 2e 0a  r of arguments..
2e190 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68  **.** The fourth
2e1a0 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
2e1b0 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
2e1c0 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
2e1d0 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
2e1e0 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
2e1f0 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
2e200 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
2e210 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20  eters.  Any SQL 
2e220 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2e230 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  ntation should b
2e240 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a  e able to work.*
2e250 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d  * work with UTF-
2e260 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20  8, UTF-16le, or 
2e270 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73  UTF-16be.  But s
2e280 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ome implementati
2e290 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f  ons may be.** mo
2e2a0 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74  re efficient wit
2e2b0 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74  h one encoding t
2e2c0 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 49 74  han another.  It
2e2d0 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 0a 2a   is allowed to.*
2e2e0 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
2e2f0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2e300 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
2e310 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2e320 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
2e330 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
2e340 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
2e350 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
2e360 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
2e370 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69 70  ..** When multip
2e380 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2e390 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
2e3a0 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69  unction are avai
2e3b0 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a  lable, SQLite.**
2e3c0 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f   will pick the o
2e3d0 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73  ne that involves
2e3e0 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
2e3f0 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72  t of data conver
2e400 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72  sion..** If ther
2e410 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67  e is only a sing
2e420 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2e430 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74  n which does not
2e440 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a   care what text.
2e450 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  ** encoding is u
2e460 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  sed, then the fo
2e470 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68  urth argument sh
2e480 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f  ould be [SQLITE_
2e490 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ANY]..**.** The 
2e4a0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
2e4b0 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
2e4c0 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
2e4d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2e4e0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
2e4f0 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
2e500 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
2e510 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
2e520 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a 0a  ser_data()]..**.
2e530 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c 20  ** The seventh, 
2e540 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74 68  eighth and ninth
2e550 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75   parameters, xFu
2e560 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46  nc, xStep and xF
2e570 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69  inal, are.** poi
2e580 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75  nters to C-langu
2e590 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  age functions th
2e5a0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
2e5b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2e5c0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 41  .** aggregate. A
2e5d0 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
2e5e0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
2e5f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e600 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20  of the xFunc.** 
2e610 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20 4e  callback only, N
2e620 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68 6f  ULL pointers sho
2e630 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 61 73  uld be passed as
2e640 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
2e650 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
2e660 65 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61 74  ers. An aggregat
2e670 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
2e680 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
2e690 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74  mentation of xSt
2e6a0 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
2e6b0 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64   and NULL should
2e6c0 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78   be passed for x
2e6d0 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65 20  Func. To delete 
2e6e0 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53  an existing.** S
2e6f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  QL function or a
2e700 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e  ggregate, pass N
2e710 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ULL for all thre
2e720 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  e function callb
2e730 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  acks..**.** It i
2e740 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
2e750 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
2e760 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2e770 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
2e780 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
2e790 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
2e7a0 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
2e7b0 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
2e7c0 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
2e7d0 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66  r differing pref
2e7e0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
2e7f0 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77 69  ings.  SQLite wi
2e800 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
2e810 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 6f 73  plementation mos
2e820 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65  t closely matche
2e830 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69  s the way in whi
2e840 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75  ch the.** SQL fu
2e850 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20  nction is used. 
2e860 20 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   A function impl
2e870 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
2e880 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
2e890 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
2e8a0 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
2e8b0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
2e8c0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2e8d0 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61  n with.** a nega
2e8e0 74 69 76 65 20 6e 41 72 67 2e 20 20 41 20 66 75  tive nArg.  A fu
2e8f0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
2e900 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
2e910 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
2e920 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
2e930 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
2e940 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
2e950 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
2e960 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
2e970 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
2e980 20 0a 2a 2a 20 41 20 66 75 6e 63 74 69 6f 6e 20   .** A function 
2e990 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
2e9a0 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
2e9b0 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
2e9c0 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
2e9d0 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
2e9e0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
2e9f0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
2ea00 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
2ea10 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
2ea20 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
2ea30 0a 2a 2a 20 42 75 69 6c 74 2d 69 6e 20 66 75 6e  .** Built-in fun
2ea40 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76  ctions may be ov
2ea50 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20  erloaded by new 
2ea60 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2ea70 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ned functions..*
2ea80 2a 20 54 68 65 20 66 69 72 73 74 20 61 70 70 6c  * The first appl
2ea90 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2eaa0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
2eab0 67 69 76 65 6e 20 6e 61 6d 65 20 6f 76 65 72 72  given name overr
2eac0 69 64 65 73 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c  ides all.** buil
2ead0 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 69  t-in functions i
2eae0 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
2eaf0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2eb00 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
2eb10 61 6d 65 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  ame..** Subseque
2eb20 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  nt application-d
2eb30 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
2eb40 20 6f 66 20 74 68 65 20 73 61 6d 65 20 6e 61 6d   of the same nam
2eb50 65 20 6f 6e 6c 79 20 6f 76 65 72 72 69 64 65 20  e only override 
2eb60 0a 2a 2a 20 70 72 69 6f 72 20 61 70 70 6c 69 63  .** prior applic
2eb70 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2eb80 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65  nctions that are
2eb90 20 61 6e 20 65 78 61 63 74 20 6d 61 74 63 68 20   an exact match 
2eba0 66 6f 72 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  for the.** numbe
2ebb0 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20  r of parameters 
2ebc0 61 6e 64 20 70 72 65 66 65 72 72 65 64 20 65 6e  and preferred en
2ebd0 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e  coding..**.** An
2ebe0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2ebf0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
2ec00 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
2ec10 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
2ec20 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
2ec30 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
2ec40 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
2ec50 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
2ec60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
2ec70 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
2ec80 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
2ec90 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
2eca0 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
2ecb0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2ecc0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
2ecd0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 33 7d  :.**.** {H16103}
2ece0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   The [sqlite3_cr
2ecf0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2ed00 44 2c 58 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72 66  D,X,...)] interf
2ed10 61 63 65 20 73 68 61 6c 6c 20 62 65 68 61 76 65  ace shall behave
2ed20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 73 20  .**          as 
2ed30 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2ed40 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e 2e 2e  function(D,X,...
2ed50 29 5d 20 69 6e 20 65 76 65 72 79 20 77 61 79 20  )] in every way 
2ed60 65 78 63 65 70 74 20 74 68 61 74 20 69 74 0a 2a  except that it.*
2ed70 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74 65 72  *          inter
2ed80 70 72 65 74 73 20 74 68 65 20 58 20 61 72 67 75  prets the X argu
2ed90 6d 65 6e 74 20 61 73 20 7a 65 72 6f 2d 74 65 72  ment as zero-ter
2eda0 6d 69 6e 61 74 65 64 20 55 54 46 2d 31 36 0a 2a  minated UTF-16.*
2edb0 2a 20 20 20 20 20 20 20 20 20 20 6e 61 74 69 76  *          nativ
2edc0 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73  e byte order ins
2edd0 74 65 61 64 20 6f 66 20 61 73 20 7a 65 72 6f 2d  tead of as zero-
2ede0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
2edf0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 30 36 7d  ..**.** {H16106}
2ee00 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 69 6e   A successful in
2ee10 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  vocation of the.
2ee20 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
2ee30 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2ee40 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e  tion(D,X,N,E,...
2ee50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  )] interface sha
2ee60 6c 6c 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 20  ll register.**  
2ee70 20 20 20 20 20 20 20 20 6f 72 20 72 65 70 6c 61          or repla
2ee80 63 65 73 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ces callback fun
2ee90 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 5b 64  ctions in the [d
2eea0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2eeb0 6f 6e 5d 20 44 0a 2a 2a 20 20 20 20 20 20 20 20  on] D.**        
2eec0 20 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d    used to implem
2eed0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
2eee0 74 69 6f 6e 20 6e 61 6d 65 64 20 58 20 77 69 74  tion named X wit
2eef0 68 20 4e 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  h N parameters.*
2ef00 2a 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 68  *          and h
2ef10 61 76 69 6e 67 20 61 20 70 72 65 66 65 72 72 65  aving a preferre
2ef20 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  d text encoding 
2ef30 6f 66 20 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  of E..**.** {H16
2ef40 31 30 39 7d 20 41 20 73 75 63 63 65 73 73 66 75  109} A successfu
2ef50 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
2ef60 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2ef70 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c 53  on(D,X,N,E,P,F,S
2ef80 2c 4c 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,L)].**         
2ef90 20 73 68 61 6c 6c 20 72 65 70 6c 61 63 65 20 74   shall replace t
2efa0 68 65 20 50 2c 20 46 2c 20 53 2c 20 61 6e 64 20  he P, F, S, and 
2efb0 4c 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 61 6e  L values from an
2efc0 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 77 69  y prior calls wi
2efd0 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  th.**          t
2efe0 68 65 20 73 61 6d 65 20 44 2c 20 58 2c 20 4e 2c  he same D, X, N,
2eff0 20 61 6e 64 20 45 20 76 61 6c 75 65 73 2e 0a 2a   and E values..*
2f000 2a 0a 2a 2a 20 7b 48 31 36 31 31 32 7d 20 54 68  *.** {H16112} Th
2f010 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
2f020 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 2e  e_function(D,X,.
2f030 2e 2e 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73  ..)] interface s
2f040 68 61 6c 6c 20 66 61 69 6c 0a 2a 2a 20 20 20 20  hall fail.**    
2f050 20 20 20 20 20 20 69 66 20 74 68 65 20 53 51 4c        if the SQL
2f060 20 66 75 6e 63 74 69 6f 6e 20 6e 61 6d 65 20 58   function name X
2f070 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   is.**          
2f080 6c 6f 6e 67 65 72 20 74 68 61 6e 20 32 35 35 20  longer than 255 
2f090 62 79 74 65 73 20 65 78 63 6c 75 73 69 76 65 20  bytes exclusive 
2f0a0 6f 66 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  of the zero term
2f0b0 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48  inator..**.** {H
2f0c0 31 36 31 31 38 7d 20 54 68 65 20 5b 73 71 6c 69  16118} The [sqli
2f0d0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f0e0 69 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46 2c  ion(D,X,N,E,P,F,
2f0f0 53 2c 4c 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  S,L)] interface.
2f100 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68 61 6c  **          shal
2f110 6c 20 66 61 69 6c 20 75 6e 6c 65 73 73 20 65 69  l fail unless ei
2f120 74 68 65 72 20 46 20 69 73 20 4e 55 4c 4c 20 61  ther F is NULL a
2f130 6e 64 20 53 20 61 6e 64 20 4c 20 61 72 65 20 6e  nd S and L are n
2f140 6f 6e 2d 4e 55 4c 4c 20 6f 72 0a 2a 2a 2a 20 20  on-NULL or.***  
2f150 20 20 20 20 20 20 20 46 20 69 73 20 6e 6f 6e 2d         F is non-
2f160 4e 55 4c 4c 20 61 6e 64 20 53 20 61 6e 64 20 4c  NULL and S and L
2f170 20 61 72 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a   are NULL..**.**
2f180 20 7b 48 31 36 31 32 31 7d 20 54 68 65 20 5b 73   {H16121} The [s
2f190 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f1a0 6e 63 74 69 6f 6e 28 44 2c 2e 2e 2e 29 5d 20 69  nction(D,...)] i
2f1b0 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 66  nterface shall f
2f1c0 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20  ails with an.** 
2f1d0 20 20 20 20 20 20 20 20 20 65 72 72 6f 72 20 63           error c
2f1e0 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 42  ode of [SQLITE_B
2f1f0 55 53 59 5d 20 69 66 20 74 68 65 72 65 20 65 78  USY] if there ex
2f200 69 73 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  ist [prepared st
2f210 61 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 20 20 20  atements].**    
2f220 20 20 20 20 20 20 61 73 73 6f 63 69 61 74 65 64        associated
2f230 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
2f240 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2f250 44 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 34  D..**.** {H16124
2f260 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  } The [sqlite3_c
2f270 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44  reate_function(D
2f280 2c 58 2c 4e 2c 2e 2e 2e 29 5d 20 69 6e 74 65 72  ,X,N,...)] inter
2f290 66 61 63 65 20 73 68 61 6c 6c 20 66 61 69 6c 20  face shall fail 
2f2a0 77 69 74 68 0a 2a 2a 20 20 20 20 20 20 20 20 20  with.**         
2f2b0 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20 6f   an error code o
2f2c0 66 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  f [SQLITE_ERROR]
2f2d0 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 4e 20   if parameter N 
2f2e0 69 73 20 6c 65 73 73 0a 2a 2a 20 20 20 20 20 20  is less.**      
2f2f0 20 20 20 20 74 68 61 6e 20 2d 31 20 6f 72 20 67      than -1 or g
2f300 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 2e  reater than 127.
2f310 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 31 32 37 7d 20  .**.** {H16127} 
2f320 57 68 65 6e 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  When N is non-ne
2f330 67 61 74 69 76 65 2c 20 74 68 65 20 5b 73 71 6c  gative, the [sql
2f340 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f350 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e 2e 29 5d  tion(D,X,N,...)]
2f360 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 74  .**          int
2f370 65 72 66 61 63 65 20 73 68 61 6c 6c 20 72 65 67  erface shall reg
2f380 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 73 20  ister callbacks 
2f390 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f  to be invoked fo
2f3a0 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  r the.**        
2f3b0 20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a 2a    SQL function.*
2f3c0 2a 20 20 20 20 20 20 20 20 20 20 6e 61 6d 65 64  *          named
2f3d0 20 58 20 77 68 65 6e 20 74 68 65 20 6e 75 6d 62   X when the numb
2f3e0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2f3f0 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  to the SQL funct
2f400 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 20 20  ion is.**       
2f410 20 20 20 65 78 61 63 74 6c 79 20 4e 2e 0a 2a 2a     exactly N..**
2f420 0a 2a 2a 20 7b 48 31 36 31 33 30 7d 20 57 68 65  .** {H16130} Whe
2f430 6e 20 4e 20 69 73 20 2d 31 2c 20 74 68 65 20 5b  n N is -1, the [
2f440 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2f450 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 2e 2e  unction(D,X,N,..
2f460 2e 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  .)].**          
2f470 69 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20  interface shall 
2f480 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
2f490 6b 73 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ks to be invoked
2f4a0 20 66 6f 72 20 74 68 65 20 53 51 4c 0a 2a 2a 20   for the SQL.** 
2f4b0 20 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f           functio
2f4c0 6e 20 6e 61 6d 65 64 20 58 20 77 69 74 68 20 61  n named X with a
2f4d0 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
2f4e0 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  uments..**.** {H
2f4f0 31 36 31 33 33 7d 20 57 68 65 6e 20 63 61 6c 6c  16133} When call
2f500 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  s to [sqlite3_cr
2f510 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c  eate_function(D,
2f520 58 2c 4e 2c 2e 2e 2e 29 5d 0a 2a 2a 20 20 20 20  X,N,...)].**    
2f530 20 20 20 20 20 20 73 70 65 63 69 66 79 20 6d 75        specify mu
2f540 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
2f550 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2f560 6d 65 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a  me function X.**
2f570 20 20 20 20 20 20 20 20 20 20 61 6e 64 20 77 68            and wh
2f580 65 6e 20 6f 6e 65 20 69 6d 70 6c 65 6d 65 6e 74  en one implement
2f590 61 74 69 6f 6e 20 68 61 73 20 4e 3e 3d 30 20 61  ation has N>=0 a
2f5a0 6e 64 20 74 68 65 20 6f 74 68 65 72 20 68 61 73  nd the other has
2f5b0 20 4e 3d 28 2d 31 29 0a 2a 2a 20 20 20 20 20 20   N=(-1).**      
2f5c0 20 20 20 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e      the implemen
2f5d0 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
2f5e0 6e 2d 7a 65 72 6f 20 4e 20 73 68 61 6c 6c 20 62  n-zero N shall b
2f5f0 65 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a  e preferred..**.
2f600 2a 2a 20 7b 48 31 36 31 33 36 7d 20 57 68 65 6e  ** {H16136} When
2f610 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
2f620 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2f630 6f 6e 28 44 2c 58 2c 4e 2c 45 2c 2e 2e 2e 29 5d  on(D,X,N,E,...)]
2f640 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 70 65  .**          spe
2f650 63 69 66 79 20 6d 75 6c 74 69 70 6c 65 20 69 6d  cify multiple im
2f660 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2f670 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2f680 6f 6e 20 58 20 77 69 74 68 0a 2a 2a 20 20 20 20  on X with.**    
2f690 20 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 6e        the same n
2f6a0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2f6b0 74 73 20 4e 20 62 75 74 20 77 69 74 68 20 64 69  ts N but with di
2f6c0 66 66 65 72 65 6e 74 0a 2a 2a 20 20 20 20 20 20  fferent.**      
2f6d0 20 20 20 20 65 6e 63 6f 64 69 6e 67 73 20 45 2c      encodings E,
2f6e0 20 74 68 65 6e 20 74 68 65 20 69 6d 70 6c 65 6d   then the implem
2f6f0 65 6e 74 61 74 69 6f 6e 20 77 68 65 72 65 20 45  entation where E
2f700 20 6d 61 74 63 68 65 73 20 74 68 65 0a 2a 2a 20   matches the.** 
2f710 20 20 20 20 20 20 20 20 20 64 61 74 61 62 61 73           databas
2f720 65 20 65 6e 63 6f 64 69 6e 67 20 73 68 61 6c 6c  e encoding shall
2f730 20 70 72 65 66 65 72 72 65 64 2e 0a 2a 2a 0a 2a   preferred..**.*
2f740 2a 20 7b 48 31 36 31 33 39 7d 20 46 6f 72 20 61  * {H16139} For a
2f750 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
2f760 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 65 64  function created
2f770 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20   using.**       
2f780 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61     [sqlite3_crea
2f790 74 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c  te_function(D,X,
2f7a0 4e 2c 45 2c 50 2c 30 2c 53 2c 4c 29 5d 20 74 68  N,E,P,0,S,L)] th
2f7b0 65 20 66 69 6e 61 6c 69 7a 65 72 0a 2a 2a 20 20  e finalizer.**  
2f7c0 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e          function
2f7d0 20 4c 20 73 68 61 6c 6c 20 61 6c 77 61 79 73 20   L shall always 
2f7e0 62 65 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74  be invoked exact
2f7f0 6c 79 20 6f 6e 63 65 20 69 66 20 74 68 65 0a 2a  ly once if the.*
2f800 2a 20 20 20 20 20 20 20 20 20 20 73 74 65 70 20  *          step 
2f810 66 75 6e 63 74 69 6f 6e 20 53 20 69 73 20 63 61  function S is ca
2f820 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
2f830 20 74 69 6d 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48   times..**.** {H
2f840 31 36 31 34 32 7d 20 57 68 65 6e 20 53 51 4c 69  16142} When SQLi
2f850 74 65 20 69 6e 76 6f 6b 65 73 20 65 69 74 68 65  te invokes eithe
2f860 72 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78  r the xFunc or x
2f870 53 74 65 70 20 66 75 6e 63 74 69 6f 6e 20 6f 66  Step function of
2f880 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 6e 20  .**          an 
2f890 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2f8a0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2f8b0 20 6f 72 20 61 67 67 72 65 67 61 74 65 20 63 72   or aggregate cr
2f8c0 65 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  eated.**        
2f8d0 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 72    by [sqlite3_cr
2f8e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2f8f0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   or [sqlite3_cre
2f900 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2f910 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74  ],.**          t
2f920 68 65 6e 20 74 68 65 20 61 72 72 61 79 20 6f 66  hen the array of
2f930 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2f940 20 6f 62 6a 65 63 74 73 20 70 61 73 73 65 64 20   objects passed 
2f950 61 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  as the.**       
2f960 20 20 20 74 68 69 72 64 20 70 61 72 61 6d 65 74     third paramet
2f970 65 72 20 73 68 61 6c 6c 20 62 65 20 5b 70 72 6f  er shall be [pro
2f980 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2f990 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2f9a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
2f9b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
2f9c0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
2f9d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
2f9e0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
2f9f0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
2fa00 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
2fa10 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
2fa20 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
2fa30 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2fa40 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2fa50 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
2fa60 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2fa70 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2fa80 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
2fa90 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
2faa0 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
2fab0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2fac0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
2fad0 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
2fae0 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
2faf0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
2fb00 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
2fb10 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
2fb20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
2fb30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2fb40 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2fb50 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
2fb60 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
2fb70 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2fb80 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2fb90 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
2fba0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
2fbb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2fbc0 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
2fbd0 73 20 7b 48 31 30 32 36 37 7d 20 3c 53 35 30 32  s {H10267} <S502
2fbe0 30 30 3e 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a  00> <H16100>.**.
2fbf0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2fc00 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
2fc10 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
2fc20 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
2fc30 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
2fc40 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
2fc50 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
2fc60 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
2fc70 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
2fc80 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2fc90 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
2fca0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2fcb0 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
2fcc0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2fcd0 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
2fce0 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
2fcf0 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
2fd00 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
2fd10 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
2fd20 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2fd30 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
2fd40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2fd50 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
2fd60 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
2fd70 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
2fd80 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
2fd90 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
2fda0 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
2fdb0 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
2fdc0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
2fdd0 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
2fde0 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
2fdf0 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
2fe00 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
2fe10 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
2fe20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
2fe30 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
2fe40 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
2fe50 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
2fe60 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
2fe70 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
2fe80 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
2fe90 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
2fea0 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
2feb0 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
2fec0 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
2fed0 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
2fee0 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
2fef0 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64   you what they d
2ff00 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
2ff10 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
2ff20 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52  ATED.SQLITE_DEPR
2ff30 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2ff40 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
2ff50 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
2ff60 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  xt*);.SQLITE_DEP
2ff70 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2ff80 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
2ff90 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
2ffa0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2ffb0 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
2ffc0 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
2ffd0 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
2ffe0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
2fff0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
30000 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
30010 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
30020 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
30030 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
30040 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
30050 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
30060 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
30070 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
30080 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
30090 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
300a0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
300b0 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  t64);.#endif../*
300c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
300d0 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63  taining SQL Func
300e0 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56  tion Parameter V
300f0 61 6c 75 65 73 20 7b 48 31 35 31 30 30 7d 20 3c  alues {H15100} <
30100 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
30110 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
30120 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
30130 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
30140 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
30150 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
30160 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
30170 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
30180 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
30190 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
301a0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
301b0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75  e..**.** The xFu
301c0 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
301d0 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
301e0 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
301f0 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
30200 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
30210 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
30220 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
30230 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
30240 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
30250 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
30260 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
30270 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
30280 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34  egates..** The 4
30290 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
302a0 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
302b0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
302c0 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
302d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
302e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
302f0 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
30300 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
30310 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
30320 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
30330 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
30340 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
30350 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
30360 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
30370 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
30380 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
30390 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
303a0 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
303b0 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
303c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
303d0 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
303e0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
303f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
30400 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
30410 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
30420 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
30430 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
30440 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  havior..**.** Th
30450 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
30460 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
30470 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
30480 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
30490 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
304a0 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f  t that  these ro
304b0 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
304c0 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
304d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
304e0 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
304f0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
30500 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
30510 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
30520 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
30530 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
30540 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
30550 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
30560 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36  xtracts a UTF-16
30570 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
30580 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
30590 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
305a0 6d 61 63 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a  machine.  The.**
305b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
305c0 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
305d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
305e0 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
305f0 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
30600 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
30610 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
30620 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
30630 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
30640 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
30650 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
30660 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
30670 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
30680 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
30690 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
306a0 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
306b0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
306c0 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
306d0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
306e0 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
306f0 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
30700 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
30710 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
30720 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
30730 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
30740 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
30750 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
30760 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
30770 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
30780 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
30790 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
307a0 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
307b0 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
307c0 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
307d0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
307e0 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
307f0 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
30800 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
30810 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
30820 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
30830 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
30840 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
30850 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
30860 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
30870 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
30880 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
30890 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
308a0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
308b0 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
308c0 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
308d0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
308e0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
308f0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
30900 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
30910 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30920 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
30930 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30940 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  t16()]..**.** Th
30950 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
30960 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
30970 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
30980 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
30990 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
309a0 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
309b0 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
309c0 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56  eters..**.** INV
309d0 41 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b  ARIANTS:.**.** {
309e0 48 31 35 31 30 33 7d 20 54 68 65 20 5b 73 71 6c  H15103} The [sql
309f0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
30a00 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
30a10 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
30a20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
30a30 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
30a40 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
30a50 20 42 4c 4f 42 20 61 6e 64 20 74 68 65 6e 0a 2a   BLOB and then.*
30a60 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
30a70 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
30a80 74 68 65 20 63 6f 6e 76 65 72 74 65 64 20 76 61  the converted va
30a90 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31  lue..**.** {H151
30aa0 30 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  06} The [sqlite3
30ab0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 56 29 5d  _value_bytes(V)]
30ac0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30ad0 6e 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  ns the.**       
30ae0 20 20 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74     number of byt
30af0 65 73 20 69 6e 20 74 68 65 20 42 4c 4f 42 20 6f  es in the BLOB o
30b00 72 20 73 74 72 69 6e 67 20 28 65 78 63 6c 75 73  r string (exclus
30b10 69 76 65 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ive of the.**   
30b20 20 20 20 20 20 20 20 7a 65 72 6f 20 74 65 72 6d         zero term
30b30 69 6e 61 74 6f 72 20 6f 6e 20 74 68 65 20 73 74  inator on the st
30b40 72 69 6e 67 29 20 74 68 61 74 20 77 61 73 20 72  ring) that was r
30b50 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
30b60 2a 20 20 20 20 20 20 20 20 20 20 6d 6f 73 74 20  *          most 
30b70 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
30b80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
30b90 6f 62 28 56 29 5d 20 6f 72 0a 2a 2a 20 20 20 20  ob(V)] or.**    
30ba0 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 76        [sqlite3_v
30bb0 61 6c 75 65 5f 74 65 78 74 28 56 29 5d 2e 0a 2a  alue_text(V)]..*
30bc0 2a 0a 2a 2a 20 7b 48 31 35 31 30 39 7d 20 54 68  *.** {H15109} Th
30bd0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
30be0 5f 62 79 74 65 73 31 36 28 56 29 5d 20 69 6e 74  _bytes16(V)] int
30bf0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
30c00 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  he.**          n
30c10 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
30c20 6e 20 74 68 65 20 73 74 72 69 6e 67 20 28 65 78  n the string (ex
30c30 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 0a 2a  clusive of the.*
30c40 2a 20 20 20 20 20 20 20 20 20 20 7a 65 72 6f 20  *          zero 
30c50 74 65 72 6d 69 6e 61 74 6f 72 20 6f 6e 20 74 68  terminator on th
30c60 65 20 73 74 72 69 6e 67 29 20 74 68 61 74 20 77  e string) that w
30c70 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  as returned by t
30c80 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d  he.**          m
30c90 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
30ca0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  to [sqlite3_valu
30cb0 65 5f 74 65 78 74 31 36 28 56 29 5d 2c 0a 2a 2a  e_text16(V)],.**
30cc0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
30cd0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
30ce0 65 28 56 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  e(V)], or [sqlit
30cf0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
30d00 65 28 56 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  e(V)]..**.** {H1
30d10 35 31 31 32 7d 20 54 68 65 20 5b 73 71 6c 69 74  5112} The [sqlit
30d20 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
30d30 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 6f  V)] interface co
30d40 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20 20 20  nverts the.**   
30d50 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74 65         [protecte
30d60 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
30d70 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f 20 61   object V into a
30d80 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
30d90 76 61 6c 75 65 20 61 6e 64 0a 2a 2a 20 20 20 20  value and.**    
30da0 20 20 20 20 20 20 72 65 74 75 72 6e 73 20 61 20        returns a 
30db0 63 6f 70 79 20 6f 66 20 74 68 61 74 20 76 61 6c  copy of that val
30dc0 75 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 31  ue..**.** {H1511
30dd0 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  5} The [sqlite3_
30de0 76 61 6c 75 65 5f 69 6e 74 28 56 29 5d 20 69 6e  value_int(V)] in
30df0 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73  terface converts
30e00 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
30e10 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
30e20 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
30e30 74 20 56 20 69 6e 74 6f 20 61 20 36 34 2d 62 69  t V into a 64-bi
30e40 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
30e50 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20   and.**         
30e60 20 72 65 74 75 72 6e 73 20 74 68 65 20 6c 6f 77   returns the low
30e70 65 72 20 33 32 20 62 69 74 73 20 6f 66 20 74 68  er 32 bits of th
30e80 61 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  at integer..**.*
30e90 2a 20 7b 48 31 35 31 31 38 7d 20 54 68 65 20 5b  * {H15118} The [
30ea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
30eb0 74 36 34 28 56 29 5d 20 69 6e 74 65 72 66 61 63  t64(V)] interfac
30ec0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
30ed0 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
30ee0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30ef0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
30f00 74 6f 20 61 20 36 34 2d 62 69 74 20 73 69 67 6e  to a 64-bit sign
30f10 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 0a 2a  ed integer and.*
30f20 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75 72  *          retur
30f30 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 61  ns a copy of tha
30f40 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
30f50 20 7b 48 31 35 31 32 31 7d 20 54 68 65 20 5b 73   {H15121} The [s
30f60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30f70 74 28 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(V)] interface 
30f80 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a 2a 20  converts the.** 
30f90 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63           [protec
30fa0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
30fb0 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e 74 6f  e] object V into
30fc0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
30fd0 65 64 20 55 54 46 2d 38 0a 2a 2a 20 20 20 20 20  ed UTF-8.**     
30fe0 20 20 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20       string and 
30ff0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
31000 72 20 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67  r to that string
31010 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 35 31 32 34 7d  ..**.** {H15124}
31020 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
31030 6c 75 65 5f 74 65 78 74 31 36 28 56 29 5d 20 69  lue_text16(V)] i
31040 6e 74 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74  nterface convert
31050 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20  s the.**        
31060 20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c    [protected sql
31070 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
31080 63 74 20 56 20 69 6e 74 6f 20 61 20 7a 65 72 6f  ct V into a zero
31090 2d 74 65 72 6d 69 6e 61 74 65 64 20 32 2d 62 79  -terminated 2-by
310a0 74 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61  te.**          a
310b0 6c 69 67 6e 65 64 20 55 54 46 2d 31 36 20 6e 61  ligned UTF-16 na
310c0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 0a  tive byte order.
310d0 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72 69  **          stri
310e0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  ng and returns a
310f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
31100 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 7b   string..**.** {
31110 48 31 35 31 32 37 7d 20 54 68 65 20 5b 73 71 6c  H15127} The [sql
31120 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
31130 36 62 65 28 56 29 5d 20 69 6e 74 65 72 66 61 63  6be(V)] interfac
31140 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 0a 2a  e converts the.*
31150 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 6f 74  *          [prot
31160 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
31170 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20 69 6e  lue] object V in
31180 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
31190 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a 20 20  ated 2-byte.**  
311a0 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65 64 20          aligned 
311b0 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61  UTF-16 big-endia
311c0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  n.**          st
311d0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
311e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
311f0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  at string..**.**
31200 20 7b 48 31 35 31 33 30 7d 20 54 68 65 20 5b 73   {H15130} The [s
31210 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
31220 74 31 36 6c 65 28 56 29 5d 20 69 6e 74 65 72 66  t16le(V)] interf
31230 61 63 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ace converts the
31240 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72  .**          [pr
31250 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
31260 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 56 20  value] object V 
31270 69 6e 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  into a zero-term
31280 69 6e 61 74 65 64 20 32 2d 62 79 74 65 0a 2a 2a  inated 2-byte.**
31290 20 20 20 20 20 20 20 20 20 20 61 6c 69 67 6e 65            aligne
312a0 64 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 2d  d UTF-16 little-
312b0 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20 20  endian.**       
312c0 20 20 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65     string and re
312d0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
312e0 74 6f 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  to that string..
312f0 2a 2a 0a 2a 2a 20 7b 48 31 35 31 33 33 7d 20 54  **.** {H15133} T
31300 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
31310 65 5f 74 79 70 65 28 56 29 5d 20 69 6e 74 65 72  e_type(V)] inter
31320 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
31330 20 20 20 20 20 20 20 20 20 6f 6e 65 20 6f 66 20           one of 
31340 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2c 20 5b  [SQLITE_NULL], [
31350 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
31360 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
31370 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
31380 4c 49 54 45 5f 54 45 58 54 5d 2c 20 6f 72 20 5b  LITE_TEXT], or [
31390 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 20 61 73 20  SQLITE_BLOB] as 
313a0 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 0a  appropriate for.
313b0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
313c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
313d0 6f 62 6a 65 63 74 20 56 2e 0a 2a 2a 0a 2a 2a 20  object V..**.** 
313e0 7b 48 31 35 31 33 36 7d 20 54 68 65 20 5b 73 71  {H15136} The [sq
313f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
31400 72 69 63 5f 74 79 70 65 28 56 29 5d 20 69 6e 74  ric_type(V)] int
31410 65 72 66 61 63 65 20 63 6f 6e 76 65 72 74 73 0a  erface converts.
31420 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20  **          the 
31430 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
31440 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
31450 20 56 20 69 6e 74 6f 20 65 69 74 68 65 72 20 61   V into either a
31460 6e 20 69 6e 74 65 67 65 72 20 6f 72 0a 2a 2a 20  n integer or.** 
31470 20 20 20 20 20 20 20 20 20 61 20 66 6c 6f 61 74           a float
31480 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
31490 69 66 20 69 74 20 63 61 6e 20 64 6f 20 73 6f 20  if it can do so 
314a0 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 0a  without loss of.
314b0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 66 6f  **          info
314c0 72 6d 61 74 69 6f 6e 2c 20 61 6e 64 20 72 65 74  rmation, and ret
314d0 75 72 6e 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  urns one of [SQL
314e0 49 54 45 5f 4e 55 4c 4c 5d 2c 0a 2a 2a 20 20 20  ITE_NULL],.**   
314f0 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 49         [SQLITE_I
31500 4e 54 45 47 45 52 5d 2c 20 5b 53 51 4c 49 54 45  NTEGER], [SQLITE
31510 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
31520 5f 54 45 58 54 5d 2c 20 6f 72 0a 2a 2a 20 20 20  _TEXT], or.**   
31530 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 42         [SQLITE_B
31540 4c 4f 42 5d 20 61 73 20 61 70 70 72 6f 70 72 69  LOB] as appropri
31550 61 74 65 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20  ate for the.**  
31560 20 20 20 20 20 20 20 20 5b 70 72 6f 74 65 63 74          [protect
31570 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
31580 5d 20 6f 62 6a 65 63 74 20 56 20 61 66 74 65 72  ] object V after
31590 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
315a0 61 74 74 65 6d 70 74 2e 0a 2a 2f 0a 63 6f 6e 73  attempt..*/.cons
315b0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
315c0 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
315d0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
315e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
315f0 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
31600 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
31610 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
31620 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31630 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
31640 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
31650 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
31660 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
31670 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
31680 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
31690 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
316a0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
316b0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
316c0 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
316d0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
316e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
316f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
31700 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
31710 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31720 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
31730 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
31740 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
31750 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
31760 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
31770 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
31780 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
31790 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
317a0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
317b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
317c0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
317d0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
317e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
317f0 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
31800 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
31810 74 65 78 74 20 7b 48 31 36 32 31 30 7d 20 3c 53  text {H16210} <S
31820 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
31830 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31840 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
31850 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
31860 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  his routine to a
31870 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74 72  llocate.** a str
31880 75 63 74 75 72 65 20 66 6f 72 20 73 74 6f 72 69  ucture for stori
31890 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a  ng their state..
318a0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
318b0 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
318c0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
318d0 78 74 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  xt() routine is 
318e0 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a 2a 2a 20  called for a.** 
318f0 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
31900 67 61 74 65 2c 20 53 51 4c 69 74 65 20 61 6c 6c  gate, SQLite all
31910 6f 63 61 74 65 73 20 6e 42 79 74 65 73 20 6f 66  ocates nBytes of
31920 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
31930 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d 65 6d 6f  out that.** memo
31940 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
31950 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 2e  a pointer to it.
31960 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73   On second and s
31970 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
31980 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
31990 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
319a0 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
319b0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
319c0 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 68 65 20  n index,.** the 
319d0 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
319e0 65 74 75 72 6e 65 64 2e 20 54 68 65 20 69 6d 70  eturned. The imp
319f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
31a00 68 65 20 61 67 67 72 65 67 61 74 65 20 63 61 6e  he aggregate can
31a10 20 75 73 65 0a 2a 2a 20 74 68 65 20 72 65 74 75   use.** the retu
31a20 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20 61  rned buffer to a
31a30 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e 0a  ccumulate data..
31a40 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 61 75 74  **.** SQLite aut
31a50 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
31a60 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   the allocated b
31a70 75 66 66 65 72 20 77 68 65 6e 20 74 68 65 20 61  uffer when the a
31a80 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75 65 72  ggregate.** quer
31a90 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
31aa0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
31ab0 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
31ac0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
31ad0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
31ae0 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
31af0 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
31b00 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
31b10 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
31b20 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
31b30 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
31b40 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  s the aggregate 
31b50 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
31b60 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
31b70 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
31b80 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
31b90 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
31ba0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
31bb0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
31bc0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ng..**.** INVARI
31bd0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ANTS:.**.** {H16
31be0 32 31 31 7d 20 54 68 65 20 66 69 72 73 74 20 69  211} The first i
31bf0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
31c00 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
31c10 63 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 66 6f  context(C,N)] fo
31c20 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 61 20  r.**          a 
31c30 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61  particular insta
31c40 6e 63 65 20 6f 66 20 61 6e 20 61 67 67 72 65 67  nce of an aggreg
31c50 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 28 66 6f  ate function (fo
31c60 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  r a particular.*
31c70 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6e 74 65  *          conte
31c80 78 74 20 43 29 20 63 61 75 73 65 73 20 53 51 4c  xt C) causes SQL
31c90 69 74 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ite to allocate 
31ca0 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
31cb0 79 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 7a  y,.**          z
31cc0 65 72 6f 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  ero that memory,
31cd0 20 61 6e 64 20 72 65 74 75 72 6e 20 61 20 70 6f   and return a po
31ce0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 61 6c 6c  inter to the all
31cf0 6f 63 61 74 65 64 20 6d 65 6d 6f 72 79 2e 0a 2a  ocated memory..*
31d00 2a 0a 2a 2a 20 7b 48 31 36 32 31 33 7d 20 49 66  *.** {H16213} If
31d10 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
31d20 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
31d30 73 20 64 75 72 69 6e 67 0a 2a 2a 20 20 20 20 20  s during.**     
31d40 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67       [sqlite3_ag
31d50 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31d60 43 2c 4e 29 5d 20 74 68 65 6e 20 74 68 65 20 66  C,N)] then the f
31d70 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
31d80 30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 31 35  0..**.** {H16215
31d90 7d 20 53 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  } Second and sub
31da0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
31db0 6f 6e 73 20 6f 66 0a 2a 2a 20 20 20 20 20 20 20  ons of.**       
31dc0 20 20 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72     [sqlite3_aggr
31dd0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
31de0 4e 29 5d 20 66 6f 72 20 74 68 65 20 73 61 6d 65  N)] for the same
31df0 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
31e00 20 43 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69   C.**          i
31e10 67 6e 6f 72 65 20 74 68 65 20 4e 20 70 61 72 61  gnore the N para
31e20 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
31e30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
31e40 65 20 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20  e same.**       
31e50 20 20 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f     block of memo
31e60 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ry returned by t
31e70 68 65 20 66 69 72 73 74 20 69 6e 76 6f 63 61 74  he first invocat
31e80 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32  ion..**.** {H162
31e90 31 37 7d 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  17} The memory a
31ea0 6c 6c 6f 63 61 74 65 64 20 62 79 20 5b 73 71 6c  llocated by [sql
31eb0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
31ec0 6f 6e 74 65 78 74 28 43 2c 4e 29 5d 20 69 73 0a  ontext(C,N)] is.
31ed0 2a 2a 20 20 20 20 20 20 20 20 20 20 61 75 74 6f  **          auto
31ee0 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20  matically freed 
31ef0 6f 6e 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  on the next call
31f00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
31f10 65 74 28 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20  et()].**        
31f20 20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69    or [sqlite3_fi
31f30 6e 61 6c 69 7a 65 28 29 5d 20 66 6f 72 20 74 68  nalize()] for th
31f40 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
31f50 65 6d 65 6e 74 5d 20 63 6f 6e 74 61 69 6e 69 6e  ement] containin
31f60 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  g.**          th
31f70 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
31f80 74 69 6f 6e 20 61 73 73 6f 63 69 61 74 65 64 20  tion associated 
31f90 77 69 74 68 20 63 6f 6e 74 65 78 74 20 43 2e 0a  with context C..
31fa0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
31fb0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31fc0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
31fd0 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
31fe0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31ff0 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
32000 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32   Functions {H162
32010 34 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  40} <S20200>.**.
32020 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
32030 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
32040 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
32050 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
32060 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
32070 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
32080 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
32090 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
320a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
320b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
320c0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
320d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
320e0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
320f0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
32100 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
32110 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
32120 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b  ined function. {
32130 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  END}.**.** This 
32140 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
32150 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
32160 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
32170 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
32180 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
32190 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
321a0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52  ing..**.** INVAR
321b0 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31  IANTS:.**.** {H1
321c0 36 32 34 33 7d 20 54 68 65 20 5b 73 71 6c 69 74  6243} The [sqlit
321d0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 43 29 5d  e3_user_data(C)]
321e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
321f0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
32200 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 50 20 70  .**          P p
32210 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68 65 20  ointer from the 
32220 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32230 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e 2c 45  function(D,X,N,E
32240 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20 20 20  ,P,F,S,L)].**   
32250 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69 74         or [sqlit
32260 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
32270 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50 2c 46  on16(D,X,N,E,P,F
32280 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68 61 74  ,S,L)] call that
32290 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 67  .**          reg
322a0 69 73 74 65 72 65 64 20 74 68 65 20 53 51 4c 20  istered the SQL 
322b0 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63 69 61  function associa
322c0 74 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  ted with [sqlite
322d0 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a 2a 2f  3_context] C..*/
322e0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
322f0 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33  ser_data(sqlite3
32300 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
32310 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
32320 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
32330 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b   For Functions {
32340 48 31 36 32 35 30 7d 20 3c 53 36 30 36 30 30 3e  H16250} <S60600>
32350 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20200>.**.** T
32360 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
32370 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
32380 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
32390 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
323a0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
323b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
323c0 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
323d0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
323e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
323f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
32400 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
32410 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32420 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
32430 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
32440 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
32450 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
32460 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
32470 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53 3a  *.** INVARIANTS:
32480 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 35 33 7d 20  .**.** {H16253} 
32490 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
324a0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 43  text_db_handle(C
324b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
324c0 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  urns a copy of t
324d0 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 44  he.**          D
324e0 20 70 6f 69 6e 74 65 72 20 66 72 6f 6d 20 74 68   pointer from th
324f0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
32500 65 5f 66 75 6e 63 74 69 6f 6e 28 44 2c 58 2c 4e  e_function(D,X,N
32510 2c 45 2c 50 2c 46 2c 53 2c 4c 29 5d 0a 2a 2a 20  ,E,P,F,S,L)].** 
32520 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c           or [sql
32530 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
32540 74 69 6f 6e 31 36 28 44 2c 58 2c 4e 2c 45 2c 50  tion16(D,X,N,E,P
32550 2c 46 2c 53 2c 4c 29 5d 20 63 61 6c 6c 20 74 68  ,F,S,L)] call th
32560 61 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  at.**          r
32570 65 67 69 73 74 65 72 65 64 20 74 68 65 20 53 51  egistered the SQ
32580 4c 20 66 75 6e 63 74 69 6f 6e 20 61 73 73 6f 63  L function assoc
32590 69 61 74 65 64 20 77 69 74 68 20 5b 73 71 6c 69  iated with [sqli
325a0 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 2e 0a  te3_context] C..
325b0 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
325c0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
325d0 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
325e0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
325f0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
32600 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
32610 61 20 7b 48 31 36 32 37 30 7d 20 3c 53 32 30 32  a {H16270} <S202
32620 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  00>.**.** The fo
32630 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63  llowing two func
32640 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65  tions may be use
32650 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20  d by scalar SQL 
32660 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
32670 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
32680 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
32690 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
326a0 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
326b0 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
326c0 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
326d0 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
326e0 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
326f0 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
32700 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
32710 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
32720 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
32730 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
32740 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a  erved. This may.
32750 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20  ** be used, for 
32760 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20  example, to add 
32770 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
32780 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63  sion matching sc
32790 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  alar.** function
327a0 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
327b0 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
327c0 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
327d0 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a   is stored as.**
327e0 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
327f0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51  ated with the SQ
32800 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  L value passed a
32810 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  s the regular ex
32820 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74  pression.** patt
32830 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c  ern.  The compil
32840 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  ed regular expre
32850 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75  ssion can be reu
32860 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a  sed on multiple.
32870 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
32880 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
32890 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20  ion so that the 
328a0 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e  original pattern
328b0 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20   string.** does 
328c0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72  not need to be r
328d0 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63  ecompiled on eac
328e0 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a  h invocation..**
328f0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
32900 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
32910 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
32920 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
32930 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
32940 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
32950 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
32960 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
32970 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
32980 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
32990 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
329a0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
329b0 2e 20 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61  . If no metadata
329c0 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a   has been ever.*
329d0 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74  * been set for t
329e0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20  he Nth argument 
329f0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c  of the function,
32a00 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65   or if the corre
32a10 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63  sponding.** func
32a20 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68  tion parameter h
32a30 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65  as changed since
32a40 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77   the meta-data w
32a50 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20  as set,.** then 
32a60 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
32a70 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20  ata() returns a 
32a80 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
32a90 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
32aa0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
32ab0 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68  terface saves th
32ac0 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f  e metadata.** po
32ad0 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20  inted to by its 
32ae0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  3rd parameter as
32af0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f   the metadata fo
32b00 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
32b10 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
32b20 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32b30 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62  d function.  Sub
32b40 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
32b50 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
32b60 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20  auxdata() might 
32b70 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61  return this data
32b80 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e  , if it has.** n
32b90 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65  ot been destroye
32ba0 64 2e 0a 2a 2a 20 49 66 20 69 74 20 69 73 20 6e  d..** If it is n
32bb0 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
32bc0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
32bd0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75  destructor.** fu
32be0 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20  nction given by 
32bf0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
32c00 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  r to sqlite3_set
32c10 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a  _auxdata() on.**
32c20 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68   the metadata wh
32c30 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
32c40 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
32c50 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a  rameter changes.
32c60 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53  ** or when the S
32c70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
32c80 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65  pletes, whicheve
32c90 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a  r comes first..*
32ca0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66  *.** SQLite is f
32cb0 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20  ree to call the 
32cc0 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64  destructor and d
32cd0 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20  rop metadata on 
32ce0 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  any.** parameter
32cf0 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e   of any function
32d00 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 54   at any time.  T
32d10 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65  he only guarante
32d20 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  e is that.** the
32d30 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c   destructor will
32d40 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
32d50 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  e the metadata i
32d60 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a  s dropped..**.**
32d70 20 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65   In practice, me
32d80 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
32d90 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
32da0 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
32db0 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
32dc0 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
32dd0 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
32de0 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
32df0 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
32e00 20 61 6e 64 20 53 51 4c 20 76 61 72 69 61 62 6c   and SQL variabl
32e10 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es..**.** These 
32e20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
32e30 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
32e40 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
32e50 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
32e60 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
32e70 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41  ning..**.** INVA
32e80 52 49 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48  RIANTS:.**.** {H
32e90 31 36 32 37 32 7d 20 54 68 65 20 5b 73 71 6c 69  16272} The [sqli
32ea0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
32eb0 43 2c 4e 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,N)] interface 
32ec0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
32ed0 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 6f  r.**          to
32ee0 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69   metadata associ
32ef0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 4e 74  ated with the Nt
32f00 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  h parameter of t
32f10 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 0a  he SQL function.
32f20 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 6f 73  **          whos
32f30 65 20 63 6f 6e 74 65 78 74 20 69 73 20 43 2c 20  e context is C, 
32f40 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 72 65  or NULL if there
32f50 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 20   is no metadata 
32f60 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 20 20  associated.**   
32f70 20 20 20 20 20 20 20 77 69 74 68 20 74 68 61 74         with that
32f80 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
32f90 2a 20 7b 48 31 36 32 37 34 7d 20 54 68 65 20 5b  * {H16274} The [
32fa0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
32fb0 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 69 6e  ata(C,N,P,D)] in
32fc0 74 65 72 66 61 63 65 20 61 73 73 69 67 6e 73 20  terface assigns 
32fd0 61 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 20 20  a metadata.**   
32fe0 20 20 20 20 20 20 20 70 6f 69 6e 74 65 72 20 50         pointer P
32ff0 20 74 6f 20 74 68 65 20 4e 74 68 20 70 61 72 61   to the Nth para
33000 6d 65 74 65 72 20 6f 66 20 74 68 65 20 53 51 4c  meter of the SQL
33010 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 63   function with c
33020 6f 6e 74 65 78 74 20 43 2e 0a 2a 2a 0a 2a 2a 20  ontext C..**.** 
33030 7b 48 31 36 32 37 36 7d 20 53 51 4c 69 74 65 20  {H16276} SQLite 
33040 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
33050 64 65 73 74 72 75 63 74 6f 72 20 44 20 77 69 74  destructor D wit
33060 68 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  h a single argum
33070 65 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ent.**          
33080 77 68 69 63 68 20 69 73 20 74 68 65 20 6d 65 74  which is the met
33090 61 64 61 74 61 20 70 6f 69 6e 74 65 72 20 50 20  adata pointer P 
330a0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
330b0 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
330c0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
330d0 64 61 74 61 28 43 2c 4e 2c 50 2c 44 29 5d 20 77  data(C,N,P,D)] w
330e0 68 65 6e 20 53 51 4c 69 74 65 20 63 65 61 73 65  hen SQLite cease
330f0 73 20 74 6f 20 68 6f 6c 64 0a 2a 2a 20 20 20 20  s to hold.**    
33100 20 20 20 20 20 20 74 68 65 20 6d 65 74 61 64 61        the metada
33110 74 61 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 32 37  ta..**.** {H1627
33120 37 7d 20 53 51 4c 69 74 65 20 63 65 61 73 65 73  7} SQLite ceases
33130 20 74 6f 20 68 6f 6c 64 20 6d 65 74 61 64 61 74   to hold metadat
33140 61 20 66 6f 72 20 61 6e 20 53 51 4c 20 66 75 6e  a for an SQL fun
33150 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 0a  ction parameter.
33160 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65 6e  **          when
33170 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
33180 61 74 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  at parameter cha
33190 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  nges..**.** {H16
331a0 32 37 38 7d 20 57 68 65 6e 20 5b 73 71 6c 69 74  278} When [sqlit
331b0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
331c0 2c 4e 2c 50 2c 44 29 5d 20 69 73 20 69 6e 76 6f  ,N,P,D)] is invo
331d0 6b 65 64 2c 20 74 68 65 20 64 65 73 74 72 75 63  ked, the destruc
331e0 74 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  tor.**          
331f0 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 6e  is called for an
33200 79 20 70 72 69 6f 72 20 6d 65 74 61 64 61 74 61  y prior metadata
33210 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
33220 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
33230 6f 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63  on.**          c
33240 6f 6e 74 65 78 74 20 43 20 61 6e 64 20 70 61 72  ontext C and par
33250 61 6d 65 74 65 72 20 4e 2e 0a 2a 2a 0a 2a 2a 20  ameter N..**.** 
33260 7b 48 31 36 32 37 39 7d 20 53 51 4c 69 74 65 20  {H16279} SQLite 
33270 77 69 6c 6c 20 63 61 6c 6c 20 64 65 73 74 72 75  will call destru
33280 63 74 6f 72 73 20 66 6f 72 20 61 6e 79 20 6d 65  ctors for any me
33290 74 61 64 61 74 61 20 69 74 20 69 73 20 68 6f 6c  tadata it is hol
332a0 64 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20  ding.**         
332b0 20 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72   in a particular
332c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
332d0 6d 65 6e 74 5d 20 53 20 77 68 65 6e 20 65 69 74  ment] S when eit
332e0 68 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  her.**          
332f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
33300 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
33310 69 6e 61 6c 69 7a 65 28 53 29 5d 20 69 73 20 63  inalize(S)] is c
33320 61 6c 6c 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  alled..*/.void *
33330 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
33340 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
33350 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
33360 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
33370 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
33380 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
33390 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
333a0 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
333b0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
333c0 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
333d0 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
333e0 20 42 65 68 61 76 69 6f 72 20 7b 48 31 30 32 38   Behavior {H1028
333f0 30 7d 20 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a  0} <S30100>.**.*
33400 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
33410 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
33420 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
33430 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
33440 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
33450 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
33460 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
33470 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
33480 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73 74 72  ].  If the destr
33490 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
334a0 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
334b0 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
334c0 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
334d0 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
334e0 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
334f0 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
33500 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
33510 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
33520 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
33530 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
33540 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
33550 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
33560 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
33570 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
33580 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
33590 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
335a0 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
335b0 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
335c0 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
335d0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
335e0 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
335f0 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
33600 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
33610 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
33620 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b  ilers.  See tick
33630 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70  et #2191..*/.typ
33640 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
33650 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
33660 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
33670 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
33680 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
33690 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
336a0 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
336b0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
336c0 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
336d0 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
336e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
336f0 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
33700 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
33710 74 69 6f 6e 20 7b 48 31 36 34 30 30 7d 20 3c 53  tion {H16400} <S
33720 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20200>.**.** The
33730 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
33740 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
33750 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
33760 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
33770 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
33780 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
33790 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
337a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
337b0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
337c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
337d0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
337e0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
337f0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
33800 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
33810 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
33820 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
33830 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
33840 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
33850 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
33860 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
33870 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
33880 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33890 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
338a0 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
338b0 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
338c0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
338d0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
338e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
338f0 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74  esult_blob() int
33900 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
33910 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
33920 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
33930 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
33940 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68  o be the BLOB wh
33950 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70  ose content is p
33960 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20  ointed.** to by 
33970 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
33980 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69  eter and which i
33990 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77  s N bytes long w
339a0 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
339b0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
339c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
339d0 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
339e0 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73  lob() interfaces
339f0 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
33a00 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
33a10 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
33a20 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42  nction to be a B
33a30 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
33a40 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73  ll zero.** bytes
33a50 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
33a60 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73  size, where N is
33a70 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
33a80 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
33a90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
33aa0 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
33ab0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
33ac0 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
33ad0 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
33ae0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
33af0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f  tion to be a flo
33b00 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
33b10 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
33b20 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  y its 2nd argume
33b30 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  nt..**.** The sq
33b40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33b50 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
33b60 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
33b70 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
33b80 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
33b90 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
33ba0 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
33bb0 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51 4c 69  ception..** SQLi
33bc0 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
33bd0 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
33be0 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
33bf0 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
33c00 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
33c10 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
33c20 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
33c30 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
33c40 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
33c50 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65   SQLite interpre
33c60 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ts the error.** 
33c70 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66  message string f
33c80 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
33c90 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54  lt_error() as UT
33ca0 46 2d 38 2e 20 53 51 4c 69 74 65 0a 2a 2a 20 69  F-8. SQLite.** i
33cb0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74  nterprets the st
33cc0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
33cd0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
33ce0 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  () as UTF-16 in 
33cf0 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f  native.** byte o
33d00 72 64 65 72 2e 20 20 49 66 20 74 68 65 20 74 68  rder.  If the th
33d10 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
33d20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33d30 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
33d40 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33d50 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69  or16() is negati
33d60 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
33d70 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f  akes as the erro
33d80 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c  r.** message all
33d90 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68   text up through
33da0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
33db0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 66  character..** If
33dc0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
33dd0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
33de0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
33df0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
33e00 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
33e10 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
33e20 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
33e30 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
33e40 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
33e50 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
33e60 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
33e70 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
33e80 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
33e90 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
33ea0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
33eb0 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72  t_error16().** r
33ec0 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70  outines make a p
33ed0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
33ee0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
33ef0 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20   text before.** 
33f00 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65  they return.  He
33f10 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  nce, the calling
33f20 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65   function can de
33f30 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d  allocate or.** m
33f40 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61  odify the text a
33f50 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e  fter they return
33f60 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
33f70 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
33f80 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
33f90 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67  ) function chang
33fa0 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  es the error cod
33fb0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
33fc0 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73   SQLite as a res
33fd0 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ult of an error 
33fe0 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20  in a function.  
33ff0 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
34000 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
34010 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
34020 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
34030 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
34040 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
34050 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
34060 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
34070 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
34080 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
34090 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
340a0 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69  te3_result_toobi
340b0 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
340c0 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
340d0 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a  hrow an error.**
340e0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
340f0 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
34100 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20  B is to long to 
34110 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
34120 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
34130 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ult_nomem() inte
34140 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
34150 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
34160 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
34170 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
34180 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
34190 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  led..**.** The s
341a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
341b0 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
341c0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
341d0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
341e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
341f0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
34200 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
34210 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
34220 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
34230 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
34240 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
34250 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
34260 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
34270 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
34280 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
34290 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
342a0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
342b0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
342c0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
342d0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
342e0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  gument..**.** Th
342f0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
34300 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  _null() interfac
34310 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
34320 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
34330 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
34340 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
34350 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
34360 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
34370 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
34380 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
34390 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  6(),.** sqlite3_
343a0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
343b0 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
343c0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
343d0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
343e0 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
343f0 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
34400 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
34410 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
34420 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
34430 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
34440 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
34450 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
34460 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
34470 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
34480 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
34490 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
344a0 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 74  ely..** SQLite t
344b0 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65  akes the text re
344c0 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70  sult from the ap
344d0 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a  plication from.*
344e0 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  * the 2nd parame
344f0 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ter of the sqlit
34500 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
34510 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 49  interfaces..** I
34520 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
34530 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
34540 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
34550 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
34560 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
34570 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73  SQLite takes res
34580 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68  ult text from th
34590 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  e 2nd parameter.
345a0 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  ** through the f
345b0 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
345c0 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33  ter..** If the 3
345d0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
345e0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
345f0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
34600 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65  ces.** is non-ne
34610 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20  gative, then as 
34620 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20  many bytes (not 
34630 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74  characters) of t
34640 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74  he text.** point
34650 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64  ed to by the 2nd
34660 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74   parameter are t
34670 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c  aken as the appl
34680 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a  ication-defined.
34690 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75  ** function resu
346a0 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34 74  lt..** If the 4t
346b0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
346c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
346d0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
346e0 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
346f0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
34700 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
34710 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
34720 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
34730 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
34740 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
34750 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
34760 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
34770 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
34780 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
34790 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72  * If the 4th par
347a0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
347b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
347c0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72  t* interfaces or
347d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
347e0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
347f0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
34800 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
34810 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
34820 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
34830 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
34840 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
34850 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
34860 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
34870 20 69 74 20 6f 72 20 63 61 6c 6c 20 61 20 64 65   it or call a de
34880 73 74 72 75 63 74 6f 72 20 77 68 65 6e 20 69 74  structor when it
34890 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
348a0 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
348b0 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70  .** If the 4th p
348c0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
348d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
348e0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
348f0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
34900 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
34910 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
34920 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
34930 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
34940 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
34950 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
34960 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
34970 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
34980 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
34990 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
349a0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ns..**.** The sq
349b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
349c0 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ue() interface s
349d0 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ets the result o
349e0 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
349f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
34a00 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f  ction to be a co
34a10 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f  py the.** [unpro
34a20 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
34a30 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65  alue] object spe
34a40 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e  cified by the 2n
34a50 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
34a60 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
34a70 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
34a80 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
34a90 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
34aa0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
34ab0 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
34ac0 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
34ad0 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
34ae0 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
34af0 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
34b00 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
34b10 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
34b20 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
34b30 20 68 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f   harm..** A [pro
34b40 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
34b50 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79  alue] object may
34b60 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20   always be used 
34b70 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70  where an.** [unp
34b80 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
34b90 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69  _value] object i
34ba0 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65  s required, so e
34bb0 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66  ither.** kind of
34bc0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
34bd0 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75   object can be u
34be0 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e  sed with this in
34bf0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
34c00 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
34c10 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
34c20 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66   within the diff
34c30 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20  erent thread.** 
34c40 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e  than the one con
34c50 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c  taining the appl
34c60 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34c70 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65  function that re
34c80 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73  ceived.** the [s
34c90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
34ca0 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73  pointer, the res
34cb0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
34cc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  ed..**.** INVARI
34cd0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ANTS:.**.** {H16
34ce0 34 30 33 7d 20 54 68 65 20 64 65 66 61 75 6c 74  403} The default
34cf0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
34d00 6f 6d 20 61 6e 79 20 53 51 4c 20 66 75 6e 63 74  om any SQL funct
34d10 69 6f 6e 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ion is NULL..**.
34d20 2a 2a 20 7b 48 31 36 34 30 36 7d 20 54 68 65 20  ** {H16406} The 
34d30 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
34d40 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  blob(C,V,N,D)] i
34d50 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
34d60 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
34d70 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
34d80 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
34d90 65 20 61 20 42 4c 4f 42 20 74 68 61 74 20 69 73  e a BLOB that is
34da0 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20 20 20 20   N bytes.**     
34db0 20 20 20 20 20 69 6e 20 6c 65 6e 67 74 68 20 61       in length a
34dc0 6e 64 20 77 69 74 68 20 63 6f 6e 74 65 6e 74 20  nd with content 
34dd0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 56 2e  pointed to by V.
34de0 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 30 39 7d 20  .**.** {H16409} 
34df0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
34e00 75 6c 74 5f 64 6f 75 62 6c 65 28 43 2c 56 29 5d  ult_double(C,V)]
34e10 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
34e20 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  es the.**       
34e30 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20     return value 
34e40 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
34e50 20 62 65 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   be the floating
34e60 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 56 2e 0a   point value V..
34e70 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 32 7d 20 54  **.** {H16412} T
34e80 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
34e90 6c 74 5f 65 72 72 6f 72 28 43 2c 56 2c 4e 29 5d  lt_error(C,V,N)]
34ea0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
34eb0 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a  es the return.**
34ec0 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
34ed0 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f  of function C to
34ee0 20 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e   be an exception
34ef0 20 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65   with error code
34f00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
34f10 4c 49 54 45 5f 45 52 52 4f 52 5d 20 61 6e 64 20  LITE_ERROR] and 
34f20 61 20 55 54 46 2d 38 20 65 72 72 6f 72 20 6d 65  a UTF-8 error me
34f30 73 73 61 67 65 20 63 6f 70 69 65 64 20 66 72 6f  ssage copied fro
34f40 6d 20 56 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  m V up to the.**
34f50 20 20 20 20 20 20 20 20 20 20 66 69 72 73 74 20            first 
34f60 7a 65 72 6f 20 62 79 74 65 20 6f 72 20 75 6e 74  zero byte or unt
34f70 69 6c 20 4e 20 62 79 74 65 73 20 61 72 65 20 72  il N bytes are r
34f80 65 61 64 20 69 66 20 4e 20 69 73 20 70 6f 73 69  ead if N is posi
34f90 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  tive..**.** {H16
34fa0 34 31 35 7d 20 54 68 65 20 5b 73 71 6c 69 74 65  415} The [sqlite
34fb0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
34fc0 28 43 2c 56 2c 4e 29 5d 20 69 6e 74 65 72 66 61  (C,V,N)] interfa
34fd0 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 20 72  ce changes the r
34fe0 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20  eturn.**        
34ff0 20 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74    value of funct
35000 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e 20 65  ion C to be an e
35010 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20 65 72  xception with er
35020 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20 20 20  ror code.**     
35030 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 45 52 52       [SQLITE_ERR
35040 4f 52 5d 20 61 6e 64 20 61 20 55 54 46 2d 31 36  OR] and a UTF-16
35050 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
35060 65 72 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  er error message
35070 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 63 6f 70  .**          cop
35080 69 65 64 20 66 72 6f 6d 20 56 20 75 70 20 74 6f  ied from V up to
35090 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
350a0 74 65 72 6d 69 6e 61 74 6f 72 20 6f 72 20 75 6e  terminator or un
350b0 74 69 6c 20 4e 20 62 79 74 65 73 0a 2a 2a 20 20  til N bytes.**  
350c0 20 20 20 20 20 20 20 20 61 72 65 20 72 65 61 64          are read
350d0 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76   if N is positiv
350e0 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 31 38  e..**.** {H16418
350f0 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
35100 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
35110 69 67 28 43 29 5d 20 69 6e 74 65 72 66 61 63 65  ig(C)] interface
35120 20 63 68 61 6e 67 65 73 20 74 68 65 20 72 65 74   changes the ret
35130 75 72 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  urn.**          
35140 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 75 6e  value of the fun
35150 63 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 61 6e  ction C to be an
35160 20 65 78 63 65 70 74 69 6f 6e 20 77 69 74 68 20   exception with 
35170 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 20 20  error code.**   
35180 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 54         [SQLITE_T
35190 4f 4f 42 49 47 5d 20 61 6e 64 20 61 6e 20 61 70  OOBIG] and an ap
351a0 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20  propriate error 
351b0 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 7b  message..**.** {
351c0 48 31 36 34 32 31 7d 20 54 68 65 20 5b 73 71 6c  H16421} The [sql
351d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
351e0 72 5f 6e 6f 6d 65 6d 28 43 29 5d 20 69 6e 74 65  r_nomem(C)] inte
351f0 72 66 61 63 65 20 63 68 61 6e 67 65 73 20 74 68  rface changes th
35200 65 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20 20 20  e return.**     
35210 20 20 20 20 20 76 61 6c 75 65 20 6f 66 20 74 68       value of th
35220 65 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20  e function C to 
35230 62 65 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  be an exception 
35240 77 69 74 68 20 65 72 72 6f 72 20 63 6f 64 65 0a  with error code.
35250 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
35260 49 54 45 5f 4e 4f 4d 45 4d 5d 20 61 6e 64 20 61  ITE_NOMEM] and a
35270 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72  n appropriate er
35280 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
35290 2a 2a 20 7b 48 31 36 34 32 34 7d 20 54 68 65 20  ** {H16424} The 
352a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
352b0 65 72 72 6f 72 5f 63 6f 64 65 28 43 2c 45 29 5d  error_code(C,E)]
352c0 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67   interface chang
352d0 65 73 20 74 68 65 20 72 65 74 75 72 6e 0a 2a 2a  es the return.**
352e0 20 20 20 20 20 20 20 20 20 20 76 61 6c 75 65 20            value 
352f0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
35300 43 20 74 6f 20 62 65 20 61 6e 20 65 78 63 65 70  C to be an excep
35310 74 69 6f 6e 20 77 69 74 68 20 65 72 72 6f 72 20  tion with error 
35320 63 6f 64 65 20 45 2e 0a 2a 2a 20 20 20 20 20 20  code E..**      
35330 20 20 20 20 54 68 65 20 65 72 72 6f 72 20 6d 65      The error me
35340 73 73 61 67 65 20 74 65 78 74 20 69 73 20 75 6e  ssage text is un
35350 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b  changed..**.** {
35360 48 31 36 34 32 37 7d 20 54 68 65 20 5b 73 71 6c  H16427} The [sql
35370 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
35380 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20  C,V)] interface 
35390 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20  changes the.**  
353a0 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76          return v
353b0 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e  alue of function
353c0 20 43 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d   C to be the 32-
353d0 62 69 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75  bit integer valu
353e0 65 20 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34  e V..**.** {H164
353f0 33 30 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  30} The [sqlite3
35400 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 43 2c  _result_int64(C,
35410 56 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68  V)] interface ch
35420 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20  anges the.**    
35430 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c        return val
35440 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43  ue of function C
35450 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
35460 74 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 20  t integer value 
35470 56 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 33 33  V..**.** {H16433
35480 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  } The [sqlite3_r
35490 65 73 75 6c 74 5f 6e 75 6c 6c 28 43 29 5d 20 69  esult_null(C)] i
354a0 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
354b0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
354c0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
354d0 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
354e0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 7b 48  e NULL..**.** {H
354f0 31 36 34 33 36 7d 20 54 68 65 20 5b 73 71 6c 69  16436} The [sqli
35500 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
35510 43 2c 56 2c 4e 2c 44 29 5d 20 69 6e 74 65 72 66  C,V,N,D)] interf
35520 61 63 65 20 63 68 61 6e 67 65 73 20 74 68 65 0a  ace changes the.
35530 2a 2a 20 20 20 20 20 20 20 20 20 20 72 65 74 75  **          retu
35540 72 6e 20 76 61 6c 75 65 20 6f 66 20 66 75 6e 63  rn value of func
35550 74 69 6f 6e 20 43 20 74 6f 20 62 65 20 74 68 65  tion C to be the
35560 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
35570 20 20 20 20 20 20 20 20 20 20 56 20 75 70 20 74            V up t
35580 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
35590 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76   if N is negativ
355a0 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 72  e.**          or
355b0 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79 74   the first N byt
355c0 65 73 20 6f 66 20 56 20 69 66 20 4e 20 69 73 20  es of V if N is 
355d0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a 2a  non-negative..**
355e0 0a 2a 2a 20 7b 48 31 36 34 33 39 7d 20 54 68 65  .** {H16439} The
355f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
35600 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44 29  _text16(C,V,N,D)
35610 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
35620 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
35630 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
35640 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
35650 6f 20 62 65 20 74 68 65 20 55 54 46 2d 31 36 20  o be the UTF-16 
35660 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
35670 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74  r.**          st
35680 72 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65  ring V up to the
35690 20 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e   first zero if N
356a0 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20   is negative.** 
356b0 20 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20           or the 
356c0 66 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66  first N bytes of
356d0 20 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e   V if N is non-n
356e0 65 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b  egative..**.** {
356f0 48 31 36 34 34 32 7d 20 54 68 65 20 5b 73 71 6c  H16442} The [sql
35700 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35710 31 36 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69  16be(C,V,N,D)] i
35720 6e 74 65 72 66 61 63 65 20 63 68 61 6e 67 65 73  nterface changes
35730 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20   the.**         
35740 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
35750 20 66 75 6e 63 74 69 6f 6e 20 43 20 74 6f 20 62   function C to b
35760 65 20 74 68 65 20 55 54 46 2d 31 36 20 62 69 67  e the UTF-16 big
35770 2d 65 6e 64 69 61 6e 0a 2a 2a 20 20 20 20 20 20  -endian.**      
35780 20 20 20 20 73 74 72 69 6e 67 20 56 20 75 70 20      string V up 
35790 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
357a0 6f 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69  o if N is negati
357b0 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  ve.**          o
357c0 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 62 79  r the first N by
357d0 74 65 73 20 6f 72 20 56 20 69 66 20 4e 20 69 73  tes or V if N is
357e0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2e 0a 2a   non-negative..*
357f0 2a 0a 2a 2a 20 7b 48 31 36 34 34 35 7d 20 54 68  *.** {H16445} Th
35800 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
35810 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c 4e  t_text16le(C,V,N
35820 2c 44 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  ,D)] interface c
35830 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20 20 20  hanges the.**   
35840 20 20 20 20 20 20 20 72 65 74 75 72 6e 20 76 61         return va
35850 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20  lue of function 
35860 43 20 74 6f 20 62 65 20 74 68 65 20 55 54 46 2d  C to be the UTF-
35870 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  16 little-endian
35880 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 74 72  .**          str
35890 69 6e 67 20 56 20 75 70 20 74 6f 20 74 68 65 20  ing V up to the 
358a0 66 69 72 73 74 20 7a 65 72 6f 20 69 66 20 4e 20  first zero if N 
358b0 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 20  is negative.**  
358c0 20 20 20 20 20 20 20 20 6f 72 20 74 68 65 20 66          or the f
358d0 69 72 73 74 20 4e 20 62 79 74 65 73 20 6f 66 20  irst N bytes of 
358e0 56 20 69 66 20 4e 20 69 73 20 6e 6f 6e 2d 6e 65  V if N is non-ne
358f0 67 61 74 69 76 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  gative..**.** {H
35900 31 36 34 34 38 7d 20 54 68 65 20 5b 73 71 6c 69  16448} The [sqli
35910 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
35920 28 43 2c 56 29 5d 20 69 6e 74 65 72 66 61 63 65  (C,V)] interface
35930 20 63 68 61 6e 67 65 73 20 74 68 65 0a 2a 2a 20   changes the.** 
35940 20 20 20 20 20 20 20 20 20 72 65 74 75 72 6e 20           return 
35950 76 61 6c 75 65 20 6f 66 20 66 75 6e 63 74 69 6f  value of functio
35960 6e 20 43 20 74 6f 20 62 65 20 74 68 65 20 5b 75  n C to be the [u
35970 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
35980 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 20 20 20  e3_value].**    
35990 20 20 20 20 20 20 6f 62 6a 65 63 74 20 56 2e 0a        object V..
359a0 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 31 7d 20 54  **.** {H16451} T
359b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
359c0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29  lt_zeroblob(C,N)
359d0 5d 20 69 6e 74 65 72 66 61 63 65 20 63 68 61 6e  ] interface chan
359e0 67 65 73 20 74 68 65 0a 2a 2a 20 20 20 20 20 20  ges the.**      
359f0 20 20 20 20 72 65 74 75 72 6e 20 76 61 6c 75 65      return value
35a00 20 6f 66 20 66 75 6e 63 74 69 6f 6e 20 43 20 74   of function C t
35a10 6f 20 62 65 20 61 6e 20 4e 2d 62 79 74 65 20 42  o be an N-byte B
35a20 4c 4f 42 20 6f 66 20 61 6c 6c 20 7a 65 72 6f 73  LOB of all zeros
35a30 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 34 35 34 7d  ..**.** {H16454}
35a40 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
35a50 73 75 6c 74 5f 65 72 72 6f 72 28 29 5d 20 61 6e  sult_error()] an
35a60 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
35a70 74 5f 65 72 72 6f 72 31 36 28 29 5d 0a 2a 2a 20  t_error16()].** 
35a80 20 20 20 20 20 20 20 20 20 69 6e 74 65 72 66 61           interfa
35a90 63 65 73 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  ces make a copy 
35aa0 6f 66 20 74 68 65 69 72 20 65 72 72 6f 72 20 6d  of their error m
35ab0 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 62  essage strings b
35ac0 65 66 6f 72 65 0a 2a 2a 20 20 20 20 20 20 20 20  efore.**        
35ad0 20 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a    returning..**.
35ae0 2a 2a 20 7b 48 31 36 34 35 37 7d 20 49 66 20 74  ** {H16457} If t
35af0 68 65 20 44 20 64 65 73 74 72 75 63 74 6f 72 20  he D destructor 
35b00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
35b10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
35b20 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20  b(C,V,N,D)],.** 
35b30 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65           [sqlite
35b40 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 43 2c  3_result_text(C,
35b50 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c 69 74 65  V,N,D)], [sqlite
35b60 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
35b70 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a 20 20 20  C,V,N,D)],.**   
35b80 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
35b90 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
35ba0 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72 0a 2a 2a  C,V,N,D)], or.**
35bb0 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
35bc0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
35bd0 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20 69 73 20  le(C,V,N,D)] is 
35be0 74 68 65 20 63 6f 6e 73 74 61 6e 74 20 5b 53 51  the constant [SQ
35bf0 4c 49 54 45 5f 53 54 41 54 49 43 5d 0a 2a 2a 20  LITE_STATIC].** 
35c00 20 20 20 20 20 20 20 20 20 74 68 65 6e 20 6e 6f           then no
35c10 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 65   destructor is e
35c20 76 65 72 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68  ver called on th
35c30 65 20 70 6f 69 6e 74 65 72 20 56 20 61 6e 64 20  e pointer V and 
35c40 53 51 4c 69 74 65 0a 2a 2a 20 20 20 20 20 20 20  SQLite.**       
35c50 20 20 20 61 73 73 75 6d 65 73 20 74 68 61 74 20     assumes that 
35c60 56 20 69 73 20 69 6d 6d 75 74 61 62 6c 65 2e 0a  V is immutable..
35c70 2a 2a 0a 2a 2a 20 7b 48 31 36 34 36 30 7d 20 49  **.** {H16460} I
35c80 66 20 74 68 65 20 44 20 64 65 73 74 72 75 63 74  f the D destruct
35c90 6f 72 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  or parameter to 
35ca0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
35cb0 62 6c 6f 62 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a  blob(C,V,N,D)],.
35cc0 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c  **          [sql
35cd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35ce0 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 5b 73 71 6c  (C,V,N,D)], [sql
35cf0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35d00 31 36 28 43 2c 56 2c 4e 2c 44 29 5d 2c 0a 2a 2a  16(C,V,N,D)],.**
35d10 20 20 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74            [sqlit
35d20 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
35d30 62 65 28 43 2c 56 2c 4e 2c 44 29 5d 2c 20 6f 72  be(C,V,N,D)], or
35d40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73 71  .**          [sq
35d50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35d60 74 31 36 6c 65 28 43 2c 56 2c 4e 2c 44 29 5d 20  t16le(C,V,N,D)] 
35d70 69 73 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 0a  is the constant.
35d80 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51 4c  **          [SQL
35d90 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20 74  ITE_TRANSIENT] t
35da0 68 65 6e 20 74 68 65 20 69 6e 74 65 72 66 61 63  hen the interfac
35db0 65 73 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  es makes a copy 
35dc0 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 20  of the.**       
35dd0 20 20 20 63 6f 6e 74 65 6e 74 20 6f 66 20 56 20     content of V 
35de0 61 6e 64 20 72 65 74 61 69 6e 73 20 74 68 65 20  and retains the 
35df0 63 6f 70 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  copy..**.** {H16
35e00 34 36 33 7d 20 49 66 20 74 68 65 20 44 20 64 65  463} If the D de
35e10 73 74 72 75 63 74 6f 72 20 70 61 72 61 6d 65 74  structor paramet
35e20 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  er to [sqlite3_r
35e30 65 73 75 6c 74 5f 62 6c 6f 62 28 43 2c 56 2c 4e  esult_blob(C,V,N
35e40 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20  ,D)],.**        
35e50 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c    [sqlite3_resul
35e60 74 5f 74 65 78 74 28 43 2c 56 2c 4e 2c 44 29 5d  t_text(C,V,N,D)]
35e70 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  , [sqlite3_resul
35e80 74 5f 74 65 78 74 31 36 28 43 2c 56 2c 4e 2c 44  t_text16(C,V,N,D
35e90 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
35ea0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
35eb0 74 65 78 74 31 36 62 65 28 43 2c 56 2c 4e 2c 44  text16be(C,V,N,D
35ec0 29 5d 2c 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  )], or.**       
35ed0 20 20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75     [sqlite3_resu
35ee0 6c 74 5f 74 65 78 74 31 36 6c 65 28 43 2c 56 2c  lt_text16le(C,V,
35ef0 4e 2c 44 29 5d 20 69 73 20 73 6f 6d 65 20 76 61  N,D)] is some va
35f00 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 0a 2a  lue other than.*
35f10 2a 20 20 20 20 20 20 20 20 20 20 74 68 65 20 63  *          the c
35f20 6f 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45  onstants [SQLITE
35f30 5f 53 54 41 54 49 43 5d 20 61 6e 64 20 5b 53 51  _STATIC] and [SQ
35f40 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 20  LITE_TRANSIENT] 
35f50 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
35f60 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
35f70 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
35f80 6f 72 20 44 20 77 69 74 68 20 56 20 61 73 20 69  or D with V as i
35f90 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  ts only argument
35fa0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 68 65  .**          whe
35fb0 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
35fc0 64 20 77 69 74 68 20 74 68 65 20 56 20 76 61 6c  d with the V val
35fd0 75 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ue..*/.void sqli
35fe0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
35ff0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36000 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
36010 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
36020 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
36030 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
36040 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
36050 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20  , double);.void 
36060 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36070 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e  rror(sqlite3_con
36080 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
36090 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  r*, int);.void s
360a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
360b0 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ror16(sqlite3_co
360c0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
360d0 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
360e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
360f0 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69  rror_toobig(sqli
36100 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
36110 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
36120 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73  lt_error_nomem(s
36130 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
36140 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36150 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
36160 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36170 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
36180 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
36190 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
361a0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
361b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
361c0 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
361d0 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
361e0 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  64);.void sqlite
361f0 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71  3_result_null(sq
36200 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
36210 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36220 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65  sult_text(sqlite
36230 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
36240 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f  t char*, int, vo
36250 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
36260 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
36270 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  lt_text16(sqlite
36280 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
36290 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
362a0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
362b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
362c0 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  lt_text16le(sqli
362d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
362e0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
362f0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
36300 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
36310 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c  ult_text16be(sql
36320 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
36330 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
36340 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
36350 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36360 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74  sult_value(sqlit
36370 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
36380 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f  ite3_value*);.vo
36390 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
363a0 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
363b0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
363c0 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
363d0 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
363e0 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
363f0 6e 63 65 73 20 7b 48 31 36 36 30 30 7d 20 3c 53  nces {H16600} <S
36400 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20300>.**.** The
36410 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
36420 20 75 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77   used to add new
36430 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
36440 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  nces to the.** [
36450 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36460 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61  ion] specified a
36470 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
36480 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
36490 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20  name of the new 
364a0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
364b0 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64 20  ce is specified 
364c0 61 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  as a UTF-8 strin
364d0 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
364e0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
364f0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
36500 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36510 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
36520 54 46 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72  TF-16 string for
36530 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
36540 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49  collation16(). I
36550 6e 20 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74  n all cases.** t
36560 68 65 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65  he name is passe
36570 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
36580 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
36590 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  t..**.** The thi
365a0 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20  rd argument may 
365b0 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  be one of the co
365c0 6e 73 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f  nstants [SQLITE_
365d0 55 54 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  UTF8],.** [SQLIT
365e0 45 5f 55 54 46 31 36 4c 45 5d 20 6f 72 20 5b 53  E_UTF16LE] or [S
365f0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20  QLITE_UTF16BE], 
36600 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
36610 74 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65  the user-supplie
36620 64 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70  d.** routine exp
36630 65 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65  ects to be passe
36640 64 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  d pointers to st
36650 72 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73  rings encoded us
36660 69 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54  ing UTF-8,.** UT
36670 46 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69  F-16 little-endi
36680 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
36690 67 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g-endian, respec
366a0 74 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74  tively. The.** t
366b0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69  hird argument mi
366c0 67 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c  ght also be [SQL
366d0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
366e0 44 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  D] to indicate t
366f0 68 61 74 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69  hat.** the routi
36700 6e 65 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74  ne expects point
36710 65 72 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f  ers to 16-bit wo
36720 72 64 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e  rd aligned strin
36730 67 73 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20  gs.** of UTF-16 
36740 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
36750 74 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te order of the 
36760 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a  host computer..*
36770 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  *.** A pointer t
36780 6f 20 74 68 65 20 75 73 65 72 20 73 75 70 70 6c  o the user suppl
36790 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  ied routine must
367a0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
367b0 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67 75 6d  e fifth.** argum
367c0 65 6e 74 2e 20 20 49 66 20 69 74 20 69 73 20 4e  ent.  If it is N
367d0 55 4c 4c 2c 20 74 68 69 73 20 69 73 20 74 68 65  ULL, this is the
367e0 20 73 61 6d 65 20 61 73 20 64 65 6c 65 74 69 6e   same as deletin
367f0 67 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  g the collation.
36800 2a 2a 20 73 65 71 75 65 6e 63 65 20 28 73 6f 20  ** sequence (so 
36810 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 6e  that SQLite cann
36820 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e 79 6d 6f  ot call it anymo
36830 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20 74 69 6d  re)..** Each tim
36840 65 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  e the applicatio
36850 6e 20 73 75 70 70 6c 69 65 64 20 66 75 6e 63 74  n supplied funct
36860 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ion is invoked, 
36870 69 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20  it is passed.** 
36880 61 73 20 69 74 73 20 66 69 72 73 74 20 70 61 72  as its first par
36890 61 6d 65 74 65 72 20 61 20 63 6f 70 79 20 6f 66  ameter a copy of
368a0 20 74 68 65 20 76 6f 69 64 2a 20 70 61 73 73 65   the void* passe
368b0 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
368c0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
368d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
368e0 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  llation() or sql
368f0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36900 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a  ation16()..**.**
36910 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 61   The remaining a
36920 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
36930 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70  application-supp
36940 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 61 72 65  lied routine are
36950 20 74 77 6f 20 73 74 72 69 6e 67 73 2c 0a 2a 2a   two strings,.**
36960 20 65 61 63 68 20 72 65 70 72 65 73 65 6e 74 65   each represente
36970 64 20 62 79 20 61 20 28 6c 65 6e 67 74 68 2c 20  d by a (length, 
36980 64 61 74 61 29 20 70 61 69 72 20 61 6e 64 20 65  data) pair and e
36990 6e 63 6f 64 65 64 20 69 6e 20 74 68 65 20 65 6e  ncoded in the en
369a0 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61 74 20 77  coding.** that w
369b0 61 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  as passed as the
369c0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
369d0 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69  when the collati
369e0 6f 6e 20 73 65 71 75 65 6e 63 65 20 77 61 73 0a  on sequence was.
369f0 2a 2a 20 72 65 67 69 73 74 65 72 65 64 2e 20 7b  ** registered. {
36a00 45 4e 44 7d 20 20 54 68 65 20 61 70 70 6c 69 63  END}  The applic
36a10 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63 6f  ation defined co
36a20 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 20  llation routine 
36a30 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
36a40 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 20   negative, zero 
36a50 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 20 74  or positive if t
36a60 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20  he first string 
36a70 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a 2a  is less than,.**
36a80 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
36a90 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73  eater than the s
36aa0 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69 2e  econd string. i.
36ab0 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53 54  e. (STRING1 - ST
36ac0 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  RING2)..**.** Th
36ad0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
36ae0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
36af0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
36b00 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36b10 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  ion().** except 
36b20 74 68 61 74 20 69 74 20 74 61 6b 65 73 20 61 6e  that it takes an
36b30 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e 74 20   extra argument 
36b40 77 68 69 63 68 20 69 73 20 61 20 64 65 73 74 72  which is a destr
36b50 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74 68 65  uctor for.** the
36b60 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 54 68 65   collation.  The
36b70 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
36b80 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 63  alled when the c
36b90 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  ollation is.** d
36ba0 65 73 74 72 6f 79 65 64 20 61 6e 64 20 69 73 20  estroyed and is 
36bb0 70 61 73 73 65 64 20 61 20 63 6f 70 79 20 6f 66  passed a copy of
36bc0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
36bd0 6d 65 74 65 72 20 76 6f 69 64 2a 20 70 6f 69 6e  meter void* poin
36be0 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ter.** of the sq
36bf0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
36c00 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 20  lation_v2()..** 
36c10 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72 65 20 64  Collations are d
36c20 65 73 74 72 6f 79 65 64 20 77 68 65 6e 20 74 68  estroyed when th
36c30 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65  ey are overridde
36c40 6e 20 62 79 20 6c 61 74 65 72 20 63 61 6c 6c 73  n by later calls
36c50 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f 6c 6c 61   to the.** colla
36c60 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75  tion creation fu
36c70 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20  nctions or when 
36c80 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
36c90 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f  nnection] is clo
36ca0 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  sed.** using [sq
36cb0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
36cc0 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41 4e 54 53  **.** INVARIANTS
36cd0 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 33 7d  :.**.** {H16603}
36ce0 20 41 20 73 75 63 63 65 73 73 66 75 6c 20 63 61   A successful ca
36cf0 6c 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  ll to the.**    
36d00 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
36d10 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
36d20 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
36d30 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 20 20   interface.**   
36d40 20 20 20 20 20 20 20 72 65 67 69 73 74 65 72 73         registers
36d50 20 66 75 6e 63 74 69 6f 6e 20 46 20 61 73 20 74   function F as t
36d60 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75  he comparison fu
36d70 6e 63 74 69 6f 6e 20 75 73 65 64 20 74 6f 0a 2a  nction used to.*
36d80 2a 20 20 20 20 20 20 20 20 20 20 69 6d 70 6c 65  *          imple
36d90 6d 65 6e 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 58  ment collation X
36da0 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
36db0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 42 20  e connection] B 
36dc0 66 6f 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  for.**          
36dd0 64 61 74 61 62 61 73 65 73 20 68 61 76 69 6e 67  databases having
36de0 20 65 6e 63 6f 64 69 6e 67 20 45 2e 0a 2a 2a 0a   encoding E..**.
36df0 2a 2a 20 7b 48 31 36 36 30 34 7d 20 53 51 4c 69  ** {H16604} SQLi
36e00 74 65 20 75 6e 64 65 72 73 74 61 6e 64 73 20 74  te understands t
36e10 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20 74  he X parameter t
36e20 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  o.**          [s
36e30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36e40 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45  llation_v2(B,X,E
36e50 2c 50 2c 46 2c 44 29 5d 20 61 73 20 61 20 7a 65  ,P,F,D)] as a ze
36e60 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
36e70 20 20 20 20 20 20 20 20 20 20 55 54 46 2d 38 20            UTF-8 
36e80 73 74 72 69 6e 67 20 69 6e 20 77 68 69 63 68 20  string in which 
36e90 63 61 73 65 20 69 73 20 69 67 6e 6f 72 65 64 20  case is ignored 
36ea0 66 6f 72 20 41 53 43 49 49 20 63 68 61 72 61 63  for ASCII charac
36eb0 74 65 72 73 20 61 6e 64 0a 2a 2a 20 20 20 20 20  ters and.**     
36ec0 20 20 20 20 20 69 73 20 73 69 67 6e 69 66 69 63       is signific
36ed0 61 6e 74 20 66 6f 72 20 6e 6f 6e 2d 41 53 43 49  ant for non-ASCI
36ee0 49 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  I characters..**
36ef0 0a 2a 2a 20 7b 48 31 36 36 30 36 7d 20 53 75 63  .** {H16606} Suc
36f00 63 65 73 73 69 76 65 20 63 61 6c 6c 73 20 74 6f  cessive calls to
36f10 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36f20 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 42 2c  _collation_v2(B,
36f30 58 2c 45 2c 50 2c 46 2c 44 29 5d 0a 2a 2a 20 20  X,E,P,F,D)].**  
36f40 20 20 20 20 20 20 20 20 77 69 74 68 20 74 68 65          with the
36f50 20 73 61 6d 65 20 76 61 6c 75 65 73 20 66 6f 72   same values for
36f60 20 42 2c 20 58 2c 20 61 6e 64 20 45 2c 20 6f 76   B, X, and E, ov
36f70 65 72 72 69 64 65 20 70 72 69 6f 72 20 76 61 6c  erride prior val
36f80 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ues.**          
36f90 6f 66 20 50 2c 20 46 2c 20 61 6e 64 20 44 2e 0a  of P, F, and D..
36fa0 2a 2a 0a 2a 2a 20 7b 48 31 36 36 30 39 7d 20 49  **.** {H16609} I
36fb0 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
36fc0 20 44 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 63   D in [sqlite3_c
36fd0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
36fe0 76 32 28 42 2c 58 2c 45 2c 50 2c 46 2c 44 29 5d  v2(B,X,E,P,F,D)]
36ff0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73 20  .**          is 
37000 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 69 74  not NULL then it
37010 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
37020 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 20  argument P when 
37030 74 68 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  the.**          
37040 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
37050 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 62 79  on is dropped by
37060 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 7b   SQLite..**.** {
37070 48 31 36 36 31 32 7d 20 41 20 63 6f 6c 6c 61 74  H16612} A collat
37080 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
37090 64 72 6f 70 70 65 64 20 77 68 65 6e 20 69 74 20  dropped when it 
370a0 69 73 20 6f 76 65 72 6c 6f 61 64 65 64 2e 0a 2a  is overloaded..*
370b0 2a 0a 2a 2a 20 7b 48 31 36 36 31 35 7d 20 41 20  *.** {H16615} A 
370c0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
370d0 6f 6e 20 69 73 20 64 72 6f 70 70 65 64 20 77 68  on is dropped wh
370e0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
370f0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 20 20  connection.**   
37100 20 20 20 20 20 20 20 69 73 20 63 6c 6f 73 65 64         is closed
37110 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
37120 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  close()]..**.** 
37130 7b 48 31 36 36 31 38 7d 20 54 68 65 20 70 6f 69  {H16618} The poi
37140 6e 74 65 72 20 50 20 69 6e 20 5b 73 71 6c 69 74  nter P in [sqlit
37150 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37160 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c 46  ion_v2(B,X,E,P,F
37170 2c 44 29 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20  ,D)].**         
37180 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
37190 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
371a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
371b0 20 63 6f 6d 70 61 72 69 73 6f 6e 0a 2a 2a 20 20   comparison.**  
371c0 20 20 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e          function
371d0 20 46 20 66 6f 72 20 61 6c 6c 20 73 75 62 73 65   F for all subse
371e0 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
371f0 73 20 6f 66 20 46 2e 0a 2a 2a 0a 2a 2a 20 7b 48  s of F..**.** {H
37200 31 36 36 32 31 7d 20 41 20 63 61 6c 6c 20 74 6f  16621} A call to
37210 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
37220 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c 58 2c 45  _collation(B,X,E
37230 2c 50 2c 46 29 5d 20 69 73 20 65 78 61 63 74 6c  ,P,F)] is exactl
37240 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  y.**          th
37250 65 20 73 61 6d 65 20 61 73 20 61 20 63 61 6c 6c  e same as a call
37260 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
37270 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
37280 28 29 5d 20 77 69 74 68 0a 2a 2a 20 20 20 20 20  ()] with.**     
37290 20 20 20 20 20 74 68 65 20 73 61 6d 65 20 70 61       the same pa
372a0 72 61 6d 65 74 65 72 73 20 61 6e 64 20 61 20 4e  rameters and a N
372b0 55 4c 4c 20 64 65 73 74 72 75 63 74 6f 72 2e 0a  ULL destructor..
372c0 2a 2a 0a 2a 2a 20 7b 48 31 36 36 32 34 7d 20 46  **.** {H16624} F
372d0 6f 6c 6c 6f 77 69 6e 67 20 61 20 5b 73 71 6c 69  ollowing a [sqli
372e0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
372f0 74 69 6f 6e 5f 76 32 28 42 2c 58 2c 45 2c 50 2c  tion_v2(B,X,E,P,
37300 46 2c 44 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20  F,D)],.**       
37310 20 20 20 53 51 4c 69 74 65 20 75 73 65 73 20 74     SQLite uses t
37320 68 65 20 63 6f 6d 70 61 72 69 73 6f 6e 20 66 75  he comparison fu
37330 6e 63 74 69 6f 6e 20 46 20 66 6f 72 20 61 6c 6c  nction F for all
37340 20 74 65 78 74 20 63 6f 6d 70 61 72 69 73 6f 6e   text comparison
37350 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 70 65  .**          ope
37360 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 5b  rations on the [
37370 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37380 69 6f 6e 5d 20 42 20 6f 6e 20 74 65 78 74 20 76  ion] B on text v
37390 61 6c 75 65 73 20 74 68 61 74 0a 2a 2a 20 20 20  alues that.**   
373a0 20 20 20 20 20 20 20 75 73 65 20 74 68 65 20 63         use the c
373b0 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e 63  ollating sequenc
373c0 65 20 6e 61 6d 65 64 20 58 2e 0a 2a 2a 0a 2a 2a  e named X..**.**
373d0 20 7b 48 31 36 36 32 37 7d 20 54 68 65 20 5b 73   {H16627} The [s
373e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
373f0 6c 6c 61 74 69 6f 6e 31 36 28 42 2c 58 2c 45 2c  llation16(B,X,E,
37400 50 2c 46 29 5d 20 77 6f 72 6b 73 20 74 68 65 20  P,F)] works the 
37410 73 61 6d 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  same.**         
37420 20 61 73 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   as [sqlite3_cre
37430 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 42 2c  ate_collation(B,
37440 58 2c 45 2c 50 2c 46 29 5d 20 65 78 63 65 70 74  X,E,P,F)] except
37450 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20   that the.**    
37460 20 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20        collation 
37470 6e 61 6d 65 20 58 20 69 73 20 75 6e 64 65 72 73  name X is unders
37480 74 6f 6f 64 20 61 73 20 55 54 46 2d 31 36 20 69  tood as UTF-16 i
37490 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
374a0 64 65 72 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  der.**          
374b0 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38  instead of UTF-8
374c0 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 36 33 30 7d  ..**.** {H16630}
374d0 20 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 63   When multiple c
374e0 6f 6d 70 61 72 69 73 6f 6e 20 66 75 6e 63 74 69  omparison functi
374f0 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ons are availabl
37500 65 20 66 6f 72 20 74 68 65 20 73 61 6d 65 0a 2a  e for the same.*
37510 2a 20 20 20 20 20 20 20 20 20 20 63 6f 6c 6c 61  *          colla
37520 74 69 6e 67 20 73 65 71 75 65 6e 63 65 2c 20 53  ting sequence, S
37530 51 4c 69 74 65 20 63 68 6f 6f 73 65 73 20 74 68  QLite chooses th
37540 65 20 6f 6e 65 20 77 68 6f 73 65 20 74 65 78 74  e one whose text
37550 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 20 20 20   encoding.**    
37560 20 20 20 20 20 20 72 65 71 75 69 72 65 73 20 74        requires t
37570 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
37580 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72  of conversion fr
37590 6f 6d 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  om the default.*
375a0 2a 20 20 20 20 20 20 20 20 20 20 74 65 78 74 20  *          text 
375b0 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20  encoding of the 
375c0 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 69 6e 74  database..*/.int
375d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
375e0 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c  collation(.  sql
375f0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
37600 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
37610 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
37620 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
37630 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
37640 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
37650 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
37660 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
37670 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
37680 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  v2(.  sqlite3*, 
37690 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
376a0 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
376b0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
376c0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
376d0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
376e0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
376f0 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
37700 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
37710 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
37720 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
37730 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
37740 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  , .  const void 
37750 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54  *zName,.  int eT
37760 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a  extRep, .  void*
37770 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
37780 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
37790 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
377a0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
377b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
377c0 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43  llation Needed C
377d0 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36 37 30 30  allbacks {H16700
377e0 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20300>.**.**
377f0 20 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67   To avoid having
37800 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c   to register all
37810 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
37820 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61  nces before a da
37830 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65  tabase.** can be
37840 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20   used, a single 
37850 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
37860 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
37870 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  red with the.** 
37880 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
37890 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c  tion] to be call
378a0 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75  ed whenever an u
378b0 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
378c0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69  on.** sequence i
378d0 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  s required..**.*
378e0 2a 20 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f  * If the functio
378f0 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  n is registered 
37900 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
37910 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37920 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65  ed() API,.** the
37930 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74  n it is passed t
37940 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65  he names of unde
37950 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  fined collation 
37960 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72  sequences as str
37970 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20  ings.** encoded 
37980 69 6e 20 55 54 46 2d 38 2e 20 7b 48 31 36 37 30  in UTF-8. {H1670
37990 33 7d 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  3} If sqlite3_co
379a0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
379b0 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74  () is used,.** t
379c0 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73  he names are pas
379d0 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  sed as UTF-16 in
379e0 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20   machine native 
379f0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41  byte order..** A
37a00 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
37a10 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65  function replace
37a20 73 20 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63  s any existing c
37a30 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57  allback..**.** W
37a40 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
37a50 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65   is invoked, the
37a60 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
37a70 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79  passed is a copy
37a80 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  .** of the secon
37a90 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
37aa0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
37ab0 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73  needed() or.** s
37ac0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
37ad0 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68  _needed16().  Th
37ae0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
37af0 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  t is the databas
37b00 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
37b10 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
37b20 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
37b30 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53  SQLITE_UTF8], [S
37b40 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a  QLITE_UTF16BE],.
37b50 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ** or [SQLITE_UT
37b60 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69  F16LE], indicati
37b70 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69  ng the most desi
37b80 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68  rable form of th
37b90 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  e collation.** s
37ba0 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e  equence function
37bb0 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20   required.  The 
37bc0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
37bd0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
37be0 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20  the.** required 
37bf0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
37c00 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  ce..**.** The ca
37c10 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
37c20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20  should register 
37c30 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c  the desired coll
37c40 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
37c50 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37c60 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  ollation()], [sq
37c70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
37c80 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  lation16()], or.
37c90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
37ca0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
37cb0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49  )]..**.** INVARI
37cc0 41 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 36  ANTS:.**.** {H16
37cd0 37 30 32 7d 20 41 20 73 75 63 63 65 73 73 66 75  702} A successfu
37ce0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
37cf0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
37d00 64 65 64 28 44 2c 50 2c 46 29 5d 0a 2a 2a 20 20  ded(D,P,F)].**  
37d10 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71 6c 69          or [sqli
37d20 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
37d30 65 64 65 64 31 36 28 44 2c 50 2c 46 29 5d 20 63  eded16(D,P,F)] c
37d40 61 75 73 65 73 0a 2a 2a 20 20 20 20 20 20 20 20  auses.**        
37d50 20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20    the [database 
37d60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 74 6f  connection] D to
37d70 20 69 6e 76 6f 6b 65 20 63 61 6c 6c 62 61 63 6b   invoke callback
37d80 20 46 20 77 69 74 68 20 66 69 72 73 74 0a 2a 2a   F with first.**
37d90 20 20 20 20 20 20 20 20 20 20 70 61 72 61 6d 65            parame
37da0 74 65 72 20 50 20 77 68 65 6e 65 76 65 72 20 69  ter P whenever i
37db0 74 20 6e 65 65 64 73 20 61 20 63 6f 6d 70 61 72  t needs a compar
37dc0 69 73 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 66 6f  ison function fo
37dd0 72 20 61 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r a.**          
37de0 63 6f 6c 6c 61 74 69 6e 67 20 73 65 71 75 65 6e  collating sequen
37df0 63 65 20 74 68 61 74 20 69 74 20 64 6f 65 73 20  ce that it does 
37e00 6e 6f 74 20 6b 6e 6f 77 20 61 62 6f 75 74 2e 0a  not know about..
37e10 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 34 7d 20 45  **.** {H16704} E
37e20 61 63 68 20 73 75 63 63 65 73 73 66 75 6c 20 63  ach successful c
37e30 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
37e40 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
37e50 28 29 5d 20 6f 72 0a 2a 2a 20 20 20 20 20 20 20  ()] or.**       
37e60 20 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c     [sqlite3_coll
37e70 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
37e80 5d 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 20  ] overrides the 
37e90 63 61 6c 6c 62 61 63 6b 20 72 65 67 69 73 74 65  callback registe
37ea0 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  red.**          
37eb0 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
37ec0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37ed0 5d 20 62 79 20 70 72 69 6f 72 20 63 61 6c 6c 73  ] by prior calls
37ee0 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 20 20   to either.**   
37ef0 20 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65         interface
37f00 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 36 37 30 36 7d  ..**.** {H16706}
37f10 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   The name of the
37f20 20 72 65 71 75 65 73 74 65 64 20 63 6f 6c 6c 61   requested colla
37f30 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ting function pa
37f40 73 73 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 20  ssed in the.**  
37f50 20 20 20 20 20 20 20 20 34 74 68 20 70 61 72 61          4th para
37f60 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
37f70 6c 62 61 63 6b 20 69 73 20 69 6e 20 55 54 46 2d  lback is in UTF-
37f80 38 20 69 66 20 74 68 65 20 63 61 6c 6c 62 61 63  8 if the callbac
37f90 6b 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 77 61  k.**          wa
37fa0 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
37fb0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ng [sqlite3_coll
37fc0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20  ation_needed()] 
37fd0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  and.**          
37fe0 69 73 20 69 6e 20 55 54 46 2d 31 36 20 6e 61 74  is in UTF-16 nat
37ff0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
38000 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77  f the callback w
38010 61 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 72  as.**          r
38020 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
38030 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
38040 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
38050 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
38060 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
38070 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
38080 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  void*, .  void(*
38090 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
380a0 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
380b0 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e  nst char*).);.in
380c0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
380d0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20  ion_needed16(.  
380e0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
380f0 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  d*,.  void(*)(vo
38100 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
38110 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
38120 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
38130 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
38140 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
38150 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
38160 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
38170 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
38180 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
38190 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
381a0 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
381b0 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
381c0 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
381d0 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
381e0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
381f0 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
38200 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  e3_key(.  sqlite
38210 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
38220 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
38230 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
38240 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
38250 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
38260 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
38270 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
38280 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e  hange the key on
38290 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
382a0 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65  e.  If the curre
382b0 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  nt database is n
382c0 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c  ot.** encrypted,
382d0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
382e0 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20  ll encrypt it.  
382f0 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e  If pNew==0 or nN
38300 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61  ew==0, the.** da
38310 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70  tabase is decryp
38320 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ted..**.** The c
38330 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
38340 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
38350 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
38360 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
38370 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
38380 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
38390 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
383a0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
383b0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
383c0 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
383d0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
383e0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
383f0 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
38400 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
38410 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e  CAPI3REF: Suspen
38420 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20  d Execution For 
38430 41 20 53 68 6f 72 74 20 54 69 6d 65 20 7b 48 31  A Short Time {H1
38440 30 35 33 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a  0530} <S40410>.*
38450 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
38460 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
38470 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72  n causes the cur
38480 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73  rent thread to s
38490 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
384a0 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74  .** for at least
384b0 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c   a number of mil
384c0 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66  liseconds specif
384d0 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d  ied in its param
384e0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  eter..**.** If t
384f0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
38500 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70  tem does not sup
38510 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65  port sleep reque
38520 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c  sts with.** mill
38530 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73  isecond time res
38540 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  olution, then th
38550 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72  e time will be r
38560 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20  ounded up to.** 
38570 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f  the nearest seco
38580 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  nd. The number o
38590 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  f milliseconds o
385a0 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
385b0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
385c0 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
385d0 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
385e0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ned..**.** SQLit
385f0 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69  e implements thi
38600 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63  s interface by c
38610 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65  alling the xSlee
38620 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  p().** method of
38630 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
38640 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
38650 74 2e 0a 2a 2a 0a 2a 2a 20 49 4e 56 41 52 49 41  t..**.** INVARIA
38660 4e 54 53 3a 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35  NTS:.**.** {H105
38670 33 33 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  33} The [sqlite3
38680 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72  _sleep(M)] inter
38690 66 61 63 65 20 69 6e 76 6f 6b 65 73 20 74 68 65  face invokes the
386a0 20 78 53 6c 65 65 70 0a 2a 2a 20 20 20 20 20 20   xSleep.**      
386b0 20 20 20 20 6d 65 74 68 6f 64 20 6f 66 20 74 68      method of th
386c0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
386d0 65 33 5f 76 66 73 7c 56 46 53 5d 20 69 6e 20 6f  e3_vfs|VFS] in o
386e0 72 64 65 72 20 74 6f 0a 2a 2a 20 20 20 20 20 20  rder to.**      
386f0 20 20 20 20 73 75 73 70 65 6e 64 20 65 78 65 63      suspend exec
38700 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72  ution of the cur
38710 72 65 6e 74 20 74 68 72 65 61 64 20 66 6f 72 20  rent thread for 
38720 61 74 20 6c 65 61 73 74 0a 2a 2a 20 20 20 20 20  at least.**     
38730 20 20 20 20 20 4d 20 6d 69 6c 6c 69 73 65 63 6f       M milliseco
38740 6e 64 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 35  nds..**.** {H105
38750 33 36 7d 20 54 68 65 20 5b 73 71 6c 69 74 65 33  36} The [sqlite3
38760 5f 73 6c 65 65 70 28 4d 29 5d 20 69 6e 74 65 72  _sleep(M)] inter
38770 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
38780 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 20 20   number of.**   
38790 20 20 20 20 20 20 20 6d 69 6c 6c 69 73 65 63 6f         milliseco
387a0 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74  nds of sleep act
387b0 75 61 6c 6c 79 20 72 65 71 75 65 73 74 65 64 20  ually requested 
387c0 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  of the operating
387d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 79 73  .**          sys
387e0 74 65 6d 2c 20 77 68 69 63 68 20 6d 69 67 68 74  tem, which might
387f0 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
38800 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4d 2e  the parameter M.
38810 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
38820 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
38830 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
38840 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
38850 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
38860 79 20 46 69 6c 65 73 20 7b 48 31 30 33 31 30 7d  y Files {H10310}
38870 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20000>.**.** 
38880 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
38890 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
388a0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
388b0 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
388c0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
388d0 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
388e0 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
388f0 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
38900 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
38910 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65